Skip to content
This repository
Browse code

move PSR-1 and 2 to 'accepted'

  • Loading branch information...
commit 12d227f4bc93731b28f217f43f1ad9296c0fda7d 1 parent 38dc2dc
Paul M. Jones pmjones authored
0  proposed/PSR-1-basic.md → accepted/PSR-1-basic-coding-standard.md
File renamed without changes
0  proposed/PSR-2-advanced.md → accepted/PSR-2-coding-style-guide.md
File renamed without changes
555 proposed/PSR-1.md
Source Rendered
... ... @@ -1,555 +0,0 @@
1   -PSR-1 Coding Style Guide
2   -========================
3   -
4   -The intent of this guide is to reduce cognitive friction when scanning code
5   -from different authors. It does so by enumerating a shared set of rules and
6   -expectations about how to format PHP code.
7   -
8   -This guide is derived from commonalities among the various member projects. If
9   -one project has its own style guide, that's fine for that project. But when
10   -various authors collaborate across multiple projects, it helps to have one set
11   -of guidelines to be used among all those projects. Thus, the benefit of this
12   -guide is not in the rules themselves, but in the sharing of those rules.
13   -
14   -
15   -Overview
16   ---------
17   -
18   -Please review the remainder of this guide for details on each of the following
19   -points.
20   -
21   -- Use only `<?php` and `<?=` opening tags for PHP code; leave out the closing
22   - `?>` tag when the file contains only PHP code.
23   -
24   -- Use 4 spaces for indenting, not tabs.
25   -
26   -- There is no hard limit on line length; the soft limit is 120 characters;
27   - lines of 80 characters or less are encouraged. Do not add trailing
28   - whitespace at the end of lines. Use Unix line endings (LF).
29   -
30   -- Namespace all classes; place one blank line after the `namespace`
31   - declaration, and one blank line after the block of `use` declarations.
32   -
33   -- Declare class names in `StudlyCaps`; opening braces for classes go on the
34   - next line, and closing braces go on their own line.
35   -
36   -- Declare method names in `camelCase`; opening braces for methods go on the
37   - next line, and closing braces go on their own line.
38   -
39   -- Declare visibility on all properties and methods; declare `abstract` and
40   - `final` before the visibility, and declare `static` after the visibility.
41   -
42   -- Control structure keywords have one space after them; function and method
43   - calls do not.
44   -
45   -- Opening braces for control structures go on the same line, and closing
46   - braces go on their own line.
47   -
48   -- Opening parentheses for control structures have no space after them, and
49   - closing parentheses for control structures have no space before.
50   -
51   -
52   -General
53   --------
54   -
55   -### PHP Tags
56   -
57   -Use the long `<?php ?>` tags for PHP code. Use of short-echo `<?= ?>` tags is
58   -also allowed. Do not use the other tag variations.
59   -
60   -In files that contain only PHP, leave out the closing `?>` tag.
61   -
62   -
63   -### Character Encoding
64   -
65   -Use only UTF-8 (no BOM) for PHP code. Do not use other character encodings.
66   -
67   -
68   -### Indenting
69   -
70   -Use an indent of 4 spaces. Do not use tabs.
71   -
72   -> N.b.: Using only spaces, and not mixing spaces with tabs, helps to avoid
73   -> problems with diffs, patches, history, and annotations. The use of spaces
74   -> also makes it easy to insert fine-grained sub-indentation for inter-line
75   -> alignment.
76   -
77   -
78   -### Lines
79   -
80   -There is no hard limit on line length. The soft limit on line length is 120
81   -characters; automated style checkers must warn but not error at the soft
82   -limit. This guide encourages lines no longer than 80 characters, and
83   -encourages splitting longer lines into multiple subsequent lines of no more
84   -than 80 characters each.
85   -
86   -Use the Unix LF (linefeed) line ending on all PHP files.
87   -
88   -Do not add trailing spaces at the end of lines.
89   -
90   -Blank lines may be added to improve readability and to indicate related blocks
91   -of code.
92   -
93   -Use at most one statement per line.
94   -
95   -
96   -`namespace`, `use`, and `class`
97   --------------------------------
98   -
99   -> N.b.: Formal namespaces were introduced in PHP 5.3. Code written for 5.2.x
100   -> and before must use the pseudo-namespacing convention of `Vendor_`
101   -> prefixes on class names. Code written for PHP 5.3 and after must use
102   -> formal namespaces.
103   -
104   -All namespaces and classes are to be named with [PSR-0][] in mind. This means each
105   -class is in a file by itself, and is in a namespace of at least one level: a
106   -top-level vendor name.
107   -
108   -[PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md
109   -
110   -The `namespace` line has one blank line after it.
111   -
112   -All `use` declarations go after the `namespace` declaration. There is one
113   -`use` keyword per declaration.
114   -
115   -The `use` block has one blank line after it.
116   -
117   -Class names are in `StudlyCaps`. The opening and closing braces for the
118   -class go on their own line.
119   -
120   -The `extends` and `implements` keywords are on the same line as the class
121   -name.
122   -
123   -```php
124   -<?php
125   -namespace Vendor\Package;
126   -
127   -use FooClass;
128   -use BarClass as Bar;
129   -use OtherVendor\OtherPackage\BazClass;
130   -
131   -class ClassName extends ParentClass implements InterfaceName
132   -{
133   - // constants, properties, methods
134   -}
135   -```
136   -
137   -Lists of `implements` may be split across multiple lines, where each
138   -subsequent line is indented once. List only one interface per line.
139   -
140   -```php
141   -<?php
142   -namespace Vendor\Package;
143   -
144   -use FooClass;
145   -use BarClass as Bar;
146   -use OtherVendor\OtherPackage\BazClass;
147   -
148   -class ClassName extends ParentClass implements
149   - InterfaceName,
150   - AnotherInterfaceName,
151   - YetAnotherInterface,
152   - InterfaceInterface
153   -{
154   - // constants, properties, methods
155   -}
156   -```
157   -
158   -Class Constants, Properties, and Methods
159   -----------------------------------------
160   -
161   -> N.b.: The term "class" refers to all classes, interfaces, and traits.
162   -
163   -
164   -### Constants
165   -
166   -Class constants are all upper case with underscore separators.
167   -
168   -```php
169   -<?php
170   -namespace Vendor\Package;
171   -
172   -class ClassName
173   -{
174   - const CONSTANT_NAME = 'constant value';
175   -}
176   -```
177   -
178   -### Properties
179   -
180   -This guide expressly avoids any recommendation regarding the use of
181   -`$StudlyCaps`, `$camelCase`, or `$under_score` property names. It is often the
182   -case that property names map directly to field names in external data sources.
183   -Changing between naming conventions when changing contexts merely to suit a
184   -style guide would be counterproductive in such cases.
185   -
186   -Whatever naming convention is used must be applied consistently within a
187   -reasonable scope. That scope may be vendor-level, package-level, class-level,
188   -or method-level.
189   -
190   -Declare visibility on all properties; do not use `var` to declare a property,
191   -and declare only one property per statement. Some projects prefix property
192   -names with a single underscore to indicate protected or private visibility;
193   -this guide discourages but does not disallow that practice.
194   -
195   -A property declaration looks like the following.
196   -
197   -```php
198   -<?php
199   -namespace Vendor\Package;
200   -
201   -class ClassName
202   -{
203   - public $foo = null;
204   -}
205   -```
206   -
207   -### Methods
208   -
209   -Declare method names in `camelCase()` with no space after the method name. The
210   -opening and closing braces go on their own line. There is no space after the
211   -opening parenthesis, and there is no space before the closing parenthesis.
212   -
213   -Declare visibility on all methods. Some projects prefix method names with a
214   -single underscore to indicate protected or private visibility; this guide
215   -discourages but does not disallow that practice.
216   -
217   -A method declaration looks like the following. Note the placement of
218   -parentheses, commas, spaces, and braces:
219   -
220   -```php
221   -<?php
222   -namespace Vendor\Package;
223   -
224   -class ClassName
225   -{
226   - public function fooBarBaz($arg1, &$arg2, $arg3 = [])
227   - {
228   - // method body
229   - }
230   -}
231   -```
232   -
233   -### Method Arguments
234   -
235   -Method arguments with default values always go at the end of the argument
236   -list.
237   -
238   -```php
239   -<?php
240   -namespace Vendor\Package;
241   -
242   -class ClassName
243   -{
244   - public function foo($arg1, &$arg2, $arg3 = [])
245   - {
246   - // method body
247   - }
248   -}
249   -```
250   -
251   -Argument lists may be split across subsequent indented lines; list only one
252   -argument per line. When the argument list is split across multiple lines, the
253   -closing parenthesis and opening brace are placed together on their own line.
254   -
255   -```php
256   -<?php
257   -namespace Vendor\Package;
258   -
259   -class ClassName
260   -{
261   - public function aVeryLongMethodName(
262   - ClassTypeHint $arg1,
263   - &$arg2,
264   - array $arg3 = []
265   - ) {
266   - // method body
267   - }
268   -}
269   -```
270   -
271   -### `abstract`, `final`, and `static`
272   -
273   -When present, the `abstract` and `final` declarations precede the
274   -visibility declaration.
275   -
276   -When present, the `static` declaration comes after the visibility declaration.
277   -
278   -```php
279   -<?php
280   -namespace Vendor\Package;
281   -
282   -class ClassName
283   -{
284   - protected static $foo;
285   -
286   - abstract protected zim();
287   -
288   - final public static bar()
289   - {
290   - // method body
291   - }
292   -}
293   -```
294   -
295   -Control Structures
296   -------------------
297   -
298   -The general style rules for control structures are as follows:
299   -
300   -- one space after the control structure keyword
301   -- no space after the opening parenthesis
302   -- no space before the closing parenthesis
303   -- one space between the closing parenthesis and the opening brace
304   -- structure body indented once
305   -- closing brace on its own line, outdented once from the body
306   -
307   -Always use braces to enclose the body of each structure. This standardizes how
308   -the structures look, and reduces the likelihood of introducing errors as new
309   -lines get added to the body.
310   -
311   -
312   -### `if`, `elseif`, `else`
313   -
314   -An `if` structure looks like the following. Note the placement of parentheses,
315   -spaces, and braces; and that `else` and `elseif` are on the same line as the
316   -closing brace from the earlier body.
317   -
318   -```php
319   -<?php
320   -if ($expr1) {
321   - // if body
322   -} elseif ($expr2) {
323   - // elseif body
324   -} else {
325   - // else body;
326   -}
327   -```
328   -
329   -> N.b.: There appears to be no consistency between projects, and often not
330   -> even within the same project, on the use of `else if` vs `elseif`. This
331   -> guide encourages the use of `elseif` so that all control structures look
332   -> like single words.
333   -
334   -
335   -### `switch`, `case`
336   -
337   -A `switch` structure looks like the following. Note the placement of
338   -parentheses, spaces, and braces; the indent levels for `case` and `break`; and
339   -the presence of a `// no break` comment when a break is intentionally omitted.
340   -
341   -```php
342   -<?php
343   -switch ($expr) {
344   - case 1:
345   - echo 'First case';
346   - break;
347   - case 2:
348   - echo 'Second case';
349   - // no break
350   - default:
351   - echo 'Default case';
352   - break;
353   -}
354   -```
355   -
356   -### `while`, `do while`
357   -
358   -A `while` statement looks like the following. Note the placement of
359   -parentheses, spaces, and braces.
360   -
361   -```php
362   -<?php
363   -while ($expr) {
364   - // structure body
365   -}
366   -```
367   -
368   -Similarly, a `do while` statement looks like the following. Note the placement
369   -of parentheses, spaces, and braces.
370   -
371   -```php
372   -<?php
373   -do {
374   - // structure body;
375   -} while ($expr);
376   -```
377   -
378   -### `for`
379   -
380   -A `for` statement looks like the following. Note the placement of parentheses,
381   -spaces, and braces.
382   -
383   -```php
384   -<?php
385   -for ($i = 0; $i < 10; $i++) {
386   - // for body
387   -}
388   -```
389   -
390   -### `foreach`
391   -
392   -A `foreach` statement looks like the following. Note the placement of
393   -parentheses, spaces, and braces.
394   -
395   -```php
396   -<?php
397   -foreach ($iterable as $key => $value) {
398   - // foreach body
399   -}
400   -```
401   -
402   -### `try`, `catch`
403   -
404   -A `try catch` block looks like the following. Note the placement of
405   -parentheses, spaces, and braces.
406   -
407   -```php
408   -<?php
409   -try {
410   - // try body
411   -} catch (FirstExceptionType $e) {
412   - // catch body
413   -} catch (OtherExceptionType $e) {
414   - // catch body
415   -}
416   -```
417   -
418   -Conclusion
419   -----------
420   -
421   -There are many elements of style and practice intentionally omitted by this
422   -guide; these include but are not limited to:
423   -
424   -- Declaration of global variables and global constants
425   -
426   -- Declaration of functions outside classes, including anonymous functions
427   - and closures
428   -
429   -- Operators and assignment
430   -
431   -- Inter-line alignment
432   -
433   -- Comments and documentation blocks
434   -
435   -- Class name prefixes and suffixes
436   -
437   -- Best practices
438   -
439   -Future PSRs may revise and extend this guide to address those or other
440   -elements of style and practice.
441   -
442   -
443   -Appendices
444   -----------
445   -
446   -### Survey Data
447   -
448   - url,http://www.horde.org/apps/horde/docs/CODING_STANDARDS,http://pear.php.net/manual/en/standards.php,http://solarphp.com/manual/appendix-standards.style,http://framework.zend.com/manual/en/coding-standard.html,http://symfony.com/doc/2.0/contributing/code/standards.html,http://www.ppi.io/docs/coding-standards.html,https://github.com/ezsystems/ezp-next/wiki/codingstandards,http://book.cakephp.org/2.0/en/contributing/cakephp-coding-conventions.html,https://github.com/UnionOfRAD/lithium/wiki/Spec%3A-Coding,http://drupal.org/coding-standards,http://code.google.com/p/sabredav/,http://area51.phpbb.com/docs/31x/coding-guidelines.html,https://docs.google.com/a/zikula.org/document/edit?authkey=CPCU0Us&hgd=1&id=1fcqb93Sn-hR9c0mkN6m_tyWnmEvoswKBtSc0tKkZmJA,http://www.chisimba.com,n/a,https://github.com/Respect/project-info/blob/master/coding-standards-sample.php,n/a,Object Calisthenics for PHP,http://doc.nette.org/en/coding-standard,http://flow3.typo3.org,https://github.com/propelorm/Propel2/wiki/Coding-Standards,http://developer.joomla.org/coding-standards.html
449   - voting,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,no,no,no,?,yes,no,yes
450   - indent_type,4,4,4,4,4,tab,4,tab,tab,2,4,tab,4,4,4,4,4,4,tab,tab,4,tab
451   - line_length_limit_soft,75,75,75,75,no,85,120,120,80,80,80,no,100,80,80,?,?,120,80,120,no,150
452   - line_length_limit_hard,85,85,85,85,no,no,no,no,100,?,no,no,no,100,100,?,120,120,no,no,no,no
453   - class_names,studly,studly,studly,studly,studly,studly,studly,studly,studly,studly,studly,lower_under,studly,lower,studly,studly,studly,studly,?,studly,studly,studly
454   - class_brace_line,next,next,next,next,next,same,next,same,same,same,same,next,next,next,next,next,next,next,next,same,next,next
455   - constant_names,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper
456   - true_false_null,lower,lower,lower,lower,lower,lower,lower,lower,lower,upper,lower,lower,lower,upper,lower,lower,lower,lower,lower,upper,lower,lower
457   - method_names,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel,lower_under,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel
458   - method_brace_line,next,next,next,next,next,same,next,same,same,same,same,next,next,same,next,next,next,next,next,same,next,next
459   - control_brace_line,same,same,same,same,same,same,next,same,same,same,same,next,same,same,next,same,same,same,same,same,same,next
460   - control_space_after,yes,yes,yes,yes,yes,no,yes,yes,yes,yes,no,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes
461   - always_use_control_braces,yes,yes,yes,yes,yes,yes,no,yes,yes,yes,no,yes,yes,yes,yes,no,yes,yes,yes,yes,yes,yes
462   - else_elseif_line,same,same,same,same,same,same,next,same,same,next,same,next,same,next,next,same,same,same,same,same,same,next
463   - case_break_indent_from_switch,0/1,0/1,0/1,1/2,1/2,1/2,1/2,1/1,1/1,1/2,1/2,1/1,1/2,1/2,1/2,1/2,1/2,1/2,0/1,1/1,1/2,1/2
464   - function_space_after,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no
465   - closing_php_tag_required,no,no,no,no,no,no,no,no,yes,no,no,no,no,yes,no,no,no,no,no,yes,no,no
466   - line_endings,LF,LF,LF,LF,LF,LF,LF,LF,?,LF,?,LF,LF,LF,LF,?,,LF,?,LF,LF,LF
467   - static_or_visibility_first,static,?,static,either,either,either,visibility,visibility,visibility,either,static,either,?,visibility,?,?,either,either,visibility,visibility,static,?
468   - control_space_parens,no,no,no,no,no,no,yes,no,no,no,no,no,no,yes,?,no,no,no,no,no,no,no
469   - blank_line_after_php,no,no,no,no,yes,no,no,no,no,yes,yes,no,no,yes,?,yes,yes,no,yes,no,yes,no
470   - class_method_control_brace,next/next/same,next/next/same,next/next/same,next/next/same,next/next/same,same/same/same,next/next/next,same/same/same,same/same/same,same/same/same,same/same/same,next/next/next,next/next/same,next/same/same,next/next/next,next/next/same,next/next/same,next/next/same,next/next/same,same/same/same,next/next/same,next/next/next
471   -
472   -
473   -### Survey Results
474   -
475   - indent_type:
476   - tab: 7
477   - 2: 1
478   - 4: 14
479   - line_length_limit_soft:
480   - ?: 2
481   - no: 3
482   - 75: 4
483   - 80: 6
484   - 85: 1
485   - 100: 1
486   - 120: 4
487   - 150: 1
488   - line_length_limit_hard:
489   - ?: 2
490   - no: 11
491   - 85: 4
492   - 100: 3
493   - 120: 2
494   - class_names:
495   - ?: 1
496   - lower: 1
497   - lower_under: 1
498   - studly: 19
499   - class_brace_line:
500   - next: 16
501   - same: 6
502   - constant_names:
503   - upper: 22
504   - true_false_null:
505   - lower: 19
506   - upper: 3
507   - method_names:
508   - camel: 21
509   - lower_under: 1
510   - method_brace_line:
511   - next: 15
512   - same: 7
513   - control_brace_line:
514   - next: 4
515   - same: 18
516   - control_space_after:
517   - no: 2
518   - yes: 20
519   - always_use_control_braces:
520   - no: 3
521   - yes: 19
522   - else_elseif_line:
523   - next: 6
524   - same: 16
525   - case_break_indent_from_switch:
526   - 0/1: 4
527   - 1/1: 4
528   - 1/2: 14
529   - function_space_after:
530   - no: 22
531   - closing_php_tag_required:
532   - no: 19
533   - yes: 3
534   - line_endings:
535   - ?: 5
536   - LF: 17
537   - static_or_visibility_first:
538   - ?: 5
539   - either: 7
540   - static: 4
541   - visibility: 6
542   - control_space_parens:
543   - ?: 1
544   - no: 19
545   - yes: 2
546   - blank_line_after_php:
547   - ?: 1
548   - no: 13
549   - yes: 8
550   - class_method_control_brace:
551   - next/next/next: 4
552   - next/next/same: 11
553   - next/same/same: 1
554   - same/same/same: 6
555   -

0 comments on commit 12d227f

Please sign in to comment.
Something went wrong with that request. Please try again.