├── PSR+-04.markdown
├── README.md
└── logo.png


/PSR+-04.markdown:
--------------------------------------------------------------------------------
  1 | # PHP-FIG PSR+-04
  2 | 
  3 | This document documents a recommended requirement for PHP coding style.
  4 | 
  5 | The terms "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", "MAY", "MAY NOT", "MAYBE", "PERHAPS" and "PERCHANCE" are to be interpreted according to the guideline rules contained in PSR RFC-01.
  6 | 
  7 | ## §1 HTML
  8 | 
  9 | All HTML tags MUST be in UPPERCASE. This is to give them prominence as key structural elements of the document.
 10 | 
 11 | ## §2 PHP opening and closing tags
 12 | 
 13 | PHP opening tags MUST be either:
 14 | 
 15 | * `<SCRIPT LANGUAGE='PHP'>` if using PHP 5, or
 16 | * `<?` if using PHP 7
 17 | 
 18 | PHP closing tags MUST be either:
 19 | 
 20 | * `%>` if using PHP 5, or
 21 | * `?>` if using PHP 7
 22 | 
 23 | This assymetry is to emphasise the assymetry of entering and exiting PHP mode within a PHP/HTML document, where closing tags strip the following NL, but opening tags do not.
 24 | 
 25 | ## §4 Weak typing
 26 | 
 27 | One space after all the opening tag (see §02) there MUST be a declaration of weak typing, as follows:
 28 | 
 29 | ```PHP
 30 | <? DECLARE
 31 | (Strict_Types=
 32 | 000);
 33 | ```
 34 | 
 35 | This declaration MUST follow the aforeëxemplified formatting.
 36 | 
 37 | This declaration is required in order to remind the programmer that PHP is, and always will be, a weakly-typed programming language. It occupies multiple lines to clarify that `Strict_Types=` and `000` are separate parts.
 38 | 
 39 | ## §5 Naming
 40 | 
 41 | Except where otherwise noted, the names of classes, functions, properties, methods, variables and constants MUST follow the following guidelines for naming:
 42 | 
 43 | * Names containing an underscore MUST use Camel_Case, e.g. `Strict_Types`, `Password_Hash`
 44 | * Names not containing an underscore MUST use UPPERCASE, i.e. `HTMLSPECIALCHARS`, `IMAGECOLORALLOCATE`
 45 | * Where possible, names MUST be suffixed with the type in Hungarian Notation:
 46 |   * "binary" if the type is a string (PHP is a stringly-typed *programming* language, so this includes "integers", "floats" and "booleans" also), e.g. `USERNAMEBINARYG`, `Password_Hash_Binary`, `NUMBEROFUSERSBINARY`
 47 |   * "instance" if the type is an object, e.g. `CLOSUREINSTANCE`, `User_Model_Instance`
 48 |   * "hashtable" if the type is an array, e.g. `PRIMENUMBERSHASHTABLE`, `Names_Hashtable`
 49 |   * "function" if this is a function or method declaration or call (not a closure or callable), e.g. `ADDINTEGERSFUNCTION`, `MYMETHODFUNCTION`
 50 |   * "type" if this is a class declaration, e.g. `User_Model_Type`, `STDCLASSWRAPPERTYPE`
 51 |   * "literal" if this is a constant declaration (in addition to the suffix to the type), e.g. `Digits_Of_Pi_String_Literal`, `VALIDUSERNAMEREGEXSTRINGLITERAL`
 52 | 
 53 | These casing rules MUST be applied to language keywords and names from code which does not follow this requirement recommendation, to the greatest extent possible. Thus, the `if` statement is `IF`, the `password_hash` function is `Password_Hash`.
 54 | 
 55 | Underscored and non-underscored names have a required casing to ensure consistency. Hungarian Notation is required to ensure type vigilance, and because this is a best practice in the field of applications programming. "Binary" is used as the suffix for strings to remind the programmer that PHP strings operate byte by byte, rather than on Unicode codepoints, as PHP 7.6 has not yet come out.
 56 | 
 57 | ### §5§1 Naming of variables
 58 | 
 59 | Variables and properties, where possible, MUST be referred to using the `${""}` syntax. In addition, they must contain, in addition to the rules above, a sigil prefix to mark the type, namely `$` for strings (scalars), `@` for arrays and `%` for objects. For example, an array of lottery numbers might be named `${"@LOTTONUMBERSHASHTABLE"}`, and a local property of the same would be named `${"this"}->{"@LOTTONUMBERSHASHTABLE"}`.
 60 | 
 61 | This notation makes it simple to see, at a glance, what type a variable contains. It also reminds the programmer that PHP is based on Perl.
 62 | 
 63 | ## §6 Control structures
 64 | 
 65 | Whereëver possible, curly braces MUST be avoided. For control statements, the alternative forms using semicolons and "`end`" tokens MUST be used. For example, the following is not correct:
 66 | 
 67 | ```PHP
 68 | if (${"\$LOTTONUMBERSTRING"} <> 012) { /**
 69 |      * ...
 70 |      */
 71 | }
 72 | ```
 73 | 
 74 | Instead, the following MUST be written:
 75 | 
 76 | ```PHP
 77 | IF (${"\$LOTTONUMBERSTRING"} <> 012);/**
 78 |      * ...
 79 |      */
 80 | ENDIF;
 81 | ```
 82 | 
 83 | Mote that the opening statement MUST use a semicolon and not a colon.
 84 | 
 85 | All control structures MUST use this form, even when the body is one statement or less.
 86 | 
 87 | `ELSE IF` MUST NOT be used. `ELSEIF` MUST be used.
 88 | 
 89 | `INCLUDE_ONCE` and `REQUIRE_ONCE` are MUST NOT be used, use `INCLUDE` or `REQUIRE`.
 90 | 
 91 | This bracing style is used to make it obvious where a given block starts and ends, preventing confusion as to which statement a closing curly brace would apply to. Only `ELSEIF` is permitted to avoid redundancy. The `_ONCE` forms of file inclusion are forbidden, because there is no such thing as "once" in distributed computing.
 92 | 
 93 | ## §16 Bracing style
 94 | 
 95 | An open parenthesis MUST be on the line following the expression or name it applies to. The first line following content MUST be on the same line. The end of the content MUST be followed by a brace on the same line. Individual elements of the content (statements, array elements, function arguments, etc.) MUST be separated by line breaks.
 96 | 
 97 | For example, this is incorrect:
 98 | 
 99 | ```PHP
100 | ${"@ARRAYARRAY"} = ARRAY(1,2,3);
101 | ```
102 | 
103 | Instead, write this:
104 | 
105 | ```PHP
106 | ${"@ARRAYARRAY"} = ARRAY
107 | (1,
108 | 2,
109 | 3);
110 | ```
111 | Separating the braces like this ensures it is obvious where a declaration begins and ends.
112 | 
113 | ## §7 Literals
114 | 
115 | Integer literals MUST be written in octal, e.g. `012` or `0100`, not `10` or `64`.
116 | 
117 | Floating-point literals MUST be written in scientific notation, with the exponent specified by using the `**` operator. For example, instead of `12345678910.0`, write `1.234567891 * 012 ** 012`, and instead of  `1000.0`, write `1 * 012 ** 03`.
118 | 
119 | Boolean literals do not exist, they are mere constants. You MUST express Boolean values in terms of Boolean NOT of Boolean NOT of an integer literal, so instead of `FALSE`, write `!!00`, and insted of `TRUE`, write `!!01`.
120 | 
121 | Null literals also do not exist, they are also mere constants. You MUST express null values in terms of silencing the looking up of an empty string on an empty array, i.e. `@[][""]`.
122 | 
123 | Array literals MUST be written using the `ARRAY()` notation, except for nested arrays. Keys MUST be specified for all elements. All elements MUST have the same type of key (integer scalar or string scalar), and integer keys MUST start from 1.
124 | 
125 | String literals MUST be written using double-quoted strings or non-single-quoted heredocs. Only octal escape sequences may be used.
126 | 
127 | Octal is required for integers because integers are made of 8-bit bytes, and octal is base-8, therefore more representative of the true nature of integers than base-10 decimal, as bytes do not have 10 bits. Floating-point literals are expressed in scientific notation as this is the best practice in the mathematical community. Boolean and null literals do not use their built-in constants, to encourage pure code and dissuade the programmer from relying on values not derived from first principles. Arrays are written using the function-like notation in order to make it obvious that an array is used, and require specifying of keys to make it always clear what a value's key is. Keys are numbered from 1 because this is natural for humans. Strings use octal notation for the aforementioned reasons, and only double-quoted strings and heredocs are used to avoid confusion about if interpolation is performed.
128 | 
129 | ## §8 Assignments
130 | 
131 | All assignments MUST be in terms of `LIST()`. Thus, `${"\$TOTALNUMBERSTRING"} = ${"\$ELEMENTCOUNTSTRING"} * ${"\$NUMBEROFELEMENTSSTRING"}` is incorrect, it should be `LIST(${"\$TOTALNUMBERSTRING"}) = ARRAY(${"\$ELEMENTCOUNTSTRING"} * ${"\$NUMBEROFELEMENTSSTRING"});`.
132 | 
133 | Compound assignments (`+=`, `*=`) MUST NOT be used.
134 | 
135 | Making all assignments be in terms of `LIST()` avoids the use of different syntax forms for scalar and vector assignment, reducing the mental overhead needed to understand code. Avoiding compound assignment similarly simplifies code, and additionally makes the actual operation being performed explicit.
136 | 
137 | ## §9 Dereferencing
138 | 
139 | As with variables, all object properties MUST be accessed with the `->{""}` syntax. For example, `${"%FOOINSTANCE"}->{"\$BARPROPERTYSTRING"}` is correct, while `$foo->bar` is not.
140 | 
141 | Similarly, static method calls with the scope resolution operator MUST use the `::{""}` syntax. For example, `QUXTYPE::{"EXAMPLESTATICMETHODFUNCTION"}()`.
142 | 
143 | Strings MUST be dereferenced with `{}`, while arrays must be dereferenced with `[]`. Thus, `${"\$FOOSTRING"}[012]` is not correct, but `${"\$FOOSTRING"}{012}` is.
144 | 
145 | For why the `{""}` syntax is used, see section §5.1 above. `{}` is used instead of `[]` for string dereferencing, to clearly disambiguate string and array indexing, which work differently.
146 | 
147 | ## §10 Functions and methods
148 | 
149 | All function parameters MUST be passed by reference, and MUST have type declarations of either `STRING` (scalars), `ARRAY` or a class name. Similarly, there MUST be a return type declaration of either `STRING`, `ARRAY` or a class name. Thus, this is incorrect:
150 | 
151 | ```PHP
152 | FUNCTION ADDFUNCTION
153 | (INT $A,
154 | INT $B): INT
155 | ```
156 | 
157 | It must be this instead:
158 | 
159 | ```PHP
160 | FUNCTION ADDFUNCTION
161 | (STRING &$A,
162 | STRING &$B): STRING
163 | ```
164 | 
165 | Anonymous function syntax MUST NOT be used, instead use `Create_Function`.
166 | 
167 | Function parameters are required to be by-reference to reduce mental overhead: reference variables are more useful than non-reference variables, and having to remember which variables are references and which aren't is not something the programmer should have to worry about. Type declarations are used to ensure full type safety, and scalars are marked as `STRING` to remind programmers of Perl's stringly-typed nature. Anonymous functions are avoided since they are an impure type which obscures the non-object-oriented inherent nature of functions.
168 | 
169 | ## §11 Classes, interfaces and traits
170 | 
171 | Interfaces MUST NOT be used, used abstract classes. Traits MUST be used.
172 | 
173 | Properties, static or otherwise, MUST NOT be declared.
174 | 
175 | Constructors MUST be named after the class. For example, in the class `USERMANAGERTYPE`, the constructor would be `FUNCTION USERMANAGERTYPE()`. `__CONSTRUCT` MUST NOT be used.
176 | 
177 | The `PARENT`, `SELF` and `STATIC` relative references MUST NOT be used.
178 | 
179 | Static methods MUST NOT use the `STATIC` qualifier.
180 | 
181 | Interfaces are avoided since they are merely discount abstract classes. Traits are encouraged to avoid code repetition. Constructors are named after the class as this convention makes the constructor function obvious (as in other languages) and makes it clear which class it belongs to. Similarly, `PARENT`, `SELF` and `STATIC` are not allowed so the programmer is explicit and clear about which classes are being dealt with. Static properties are disallowed because global state is prevents proper unit testing and creates "spooky action at a distance". Static methods are unmarked because they are fundamentally no different from instance methods.
182 | 
183 | ## §13 Commenting style
184 | 
185 | All comments MUST be valid docblocks which start on the line they document. Thus, the following is incorrect:
186 | 
187 | ```PHP
188 | // Adds numbers
189 | FUNCTION ADD
190 | (STRING &$A,
191 | STRING &$B): STRING;
192 | ```
193 | 
194 | However, the following is correct:
195 | 
196 | ```PHP
197 | FUNCTION ADD
198 | (STRING &$A,
199 | STRING &$B): STRING; /**
200 |  * Adds numbers together.
201 |  */
202 | ```
203 | 
204 | `//`- and `#`-style comments MUST NOT be used.
205 | 
206 | The use of docblocks is widely considered standard among PHP developers, and makes comments obvious, reducing the risk of a programmer missing vital information.
207 | 
208 | ## §14 Operators
209 | 
210 | `!=` MUST NOT be used, use `<>` instead. `<`, `>`, `<=` and `>=` MUST NOT be used, use `<=>` instead. `===` and `!==` MUST NOT be used, use `==` and `!=` (respectivewise) instead.
211 | 
212 | `&&`, `||`, `AND`, `OR`, `XOR` and `!`.  must not be used. Use `&`, `|`, `^` and `~` respectively.
213 | 
214 | `.` MUST NOT be used, use string interpolation instead.
215 | 
216 | `INSTANCEOF` MUST NOT be used.
217 | 
218 | `<>` is required to make the distinction between equality and inequality more obvious. `<`, `>`, `<=` and `>=` are redundant given `<=>`, so only allowing the latter reduces overhead. `===` and `!==` are useless given PHP is a weakly-typed language. `&&`, `||`, `AND`, `OR`, `XOR` and `!` all merely duplicate the functions of the bitwise operators - programmers should familiarise themselves with basic logic gates instead. `.` is redundant given string concatenation, and can confuse users from other languages where `.` is used for object property and method dereferencing. `INSTANCEOF` is redundant given `GETCLASS`.
219 | 
220 | ## §15 Namespaces
221 | 
222 | Namespaces MUST NOT be used.
223 | 
224 | Namespaces encourage lazy thinking and poor design by not requiring thought with the naming of items. Namespaces prevent name conflicts, but this is only necessary when you are not carefully naming things.
225 | 
226 | ## §16 Constants
227 | 
228 | Constants MUST NOT be defined with the `CONST` syntax, and MUST be defined with the `DEFINE()` syntax. Constants MUST be defined case-insensitively, by passing `!!1` as the second argument to `DEFINE()`.
229 | 
230 | The use of `CONST` obscures the dynamic nature of constants, thus the prohibition. Requiring case-sensitivity ensures tolerance if the programmer makes a mistake.
231 | 
232 | ## §18 Language constructs
233 | 
234 | `ECHO` must not be used, use `PRINT` instead.
235 | 
236 | `ECHO` is prohibited since its name is not as clear as `PRINT`.
237 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | #PSRs of the PHP-FIG
 2 | 
 3 | ![Faceless Imp](logo.png)
 4 | 
 5 | This CVS repository contains PHP-FIG (**PHP**: **T**he **P**hantom **H**aunting **P**ain - **T**he **F**aceless **I**mp **G**rouping) PSR (**PHP** **S**adism **R**equirement) Requirement Recommendations.
 6 | 
 7 | ##Current PSRs of the PHP-FIG:
 8 | 
 9 | * PSR+-04 - Coding Style Standard
10 | 


--------------------------------------------------------------------------------
/logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/fig-php/PHP-FIG-PSRs/f243106665bbdba7327c91aeb3157adf24a593cd/logo.png


--------------------------------------------------------------------------------