From 06f945f27840b53e57795dadbc38e76f7e11ab1c Mon Sep 17 00:00:00 2001 From: Horus3 Date: Mon, 24 Feb 2014 16:42:14 +0100 Subject: init --- .../core/en/coding-standard.coding-style.html | 843 +++++++++++++++++++++ 1 file changed, 843 insertions(+) create mode 100644 zend/documentation/manual/core/en/coding-standard.coding-style.html (limited to 'zend/documentation/manual/core/en/coding-standard.coding-style.html') diff --git a/zend/documentation/manual/core/en/coding-standard.coding-style.html b/zend/documentation/manual/core/en/coding-standard.coding-style.html new file mode 100644 index 0000000..bbf6cca --- /dev/null +++ b/zend/documentation/manual/core/en/coding-standard.coding-style.html @@ -0,0 +1,843 @@ + + + + + Coding Style - Zend Framework Manual + + + + + + + + +
+ + + + + + + + +
+ Naming Conventions + +
Zend Framework Coding Standard for PHP
+ Programmer's Reference Guide
+ 		+ +
+
+

Coding Style

+ + +

PHP Code Demarcation

+ + +

+ PHP code must always be delimited by the full-form, standard + PHP tags: +

+ +
  1. <?php
    2. +
  2.  
    3. +
  3. ?>
+ + +

+ Short tags are never allowed. For files containing only PHP + code, the closing tag must always be omitted (See General standards). +

+
+ +

Strings

+ + +

String Literals

+ + +

+ When a string is literal (contains no variable substitutions), the apostrophe or + "single quote" should always be used to demarcate the string: +

+ +
  1. $a = 'Example String';
+ +
+ +

String Literals Containing Apostrophes

+ + +

+ When a literal string itself contains apostrophes, it is permitted to demarcate + the string with quotation marks or "double quotes". This is especially useful + for SQL statements: +

+ +
  1. $sql = "SELECT `id`, `name` from `people` "
    2. +
  2.      . "WHERE `name`='Fred' OR `name`='Susan'";
+ + +

+ This syntax is preferred over escaping apostrophes as it is much easier to read. +

+
+ +

Variable Substitution

+ + +

+ Variable substitution is permitted using either of these forms: +

+ +
  1. $greeting = "Hello $name, welcome back!";
    2. +
  2.  
    3. +
  3. $greeting = "Hello {$name}, welcome back!";
+ + +

+ For consistency, this form is not permitted: +

+ +
  1. $greeting = "Hello ${name}, welcome back!";
+ +
+ +

String Concatenation

+ + +

+ Strings must be concatenated using the "." operator. A space must always + be added before and after the "." operator to improve readability: +

+ +
  1. $company = 'Zend' . ' ' . 'Technologies';
+ + +

+ When concatenating strings with the "." operator, it is encouraged to + break the statement into multiple lines to improve readability. In these + cases, each successive line should be padded with white space such that the + "."; operator is aligned under the "=" operator: +

+ +
  1. $sql = "SELECT `id`, `name` FROM `people` "
    2. +
  2.      . "WHERE `name` = 'Susan' "
    3. +
  3.      . "ORDER BY `name` ASC ";
+ +
+
+ +

Arrays

+ + +

Numerically Indexed Arrays

+ + +

Negative numbers are not permitted as indices.

+ +

+ An indexed array may start with any non-negative number, however + all base indices besides 0 are discouraged. +

+ +

+ When declaring indexed arrays with the Array function, a trailing + space must be added after each comma delimiter to improve readability: +

+ +
  1. $sampleArray = array(1, 2, 3, 'Zend', 'Studio');
+ + +

+ It is permitted to declare multi-line indexed arrays using the "array" + construct. In this case, each successive line must be padded with spaces such + that beginning of each line is aligned: +

+ +
  1. $sampleArray = array(1, 2, 3, 'Zend', 'Studio',
    2. +
  2.                      $a, $b, $c,
    3. +
  3.                      56.44, $d, 500);
+ + +

+ Alternately, the initial array item may begin on the following line. If so, + it should be padded at one indentation level greater than the line containing + the array declaration, and all successive lines should have the same + indentation; the closing paren should be on a line by itself at the same + indentation level as the line containing the array declaration: +

+ +
  1. $sampleArray = array(
    2. +
  2.     1, 2, 3, 'Zend', 'Studio',
    3. +
  3.     $a, $b, $c,
    4. +
  4.     56.44, $d, 500,
    5. +
  5. );
+ + +

+ When using this latter declaration, we encourage using a trailing comma for + the last item in the array; this minimizes the impact of adding new items on + successive lines, and helps to ensure no parse errors occur due to a missing + comma. +

+
+ +

Associative Arrays

+ + +

+ When declaring associative arrays with the Array construct, + breaking the statement into multiple lines is encouraged. In this case, each + successive line must be padded with white space such that both the keys and the + values are aligned: +

+ +
  1. $sampleArray = array('firstKey'  => 'firstValue',
    2. +
  2.                      'secondKey' => 'secondValue');
+ + +

+ Alternately, the initial array item may begin on the following line. If so, + it should be padded at one indentation level greater than the line containing + the array declaration, and all successive lines should have the same + indentation; the closing paren should be on a line by itself at the same + indentation level as the line containing the array declaration. For + readability, the various "=>" assignment operators should be padded such that + they align. +

+ +
  1. $sampleArray = array(
    2. +
  2.     'firstKey'  => 'firstValue',
    3. +
  3.     'secondKey' => 'secondValue',
    4. +
  4. );
+ + +

+ When using this latter declaration, we encourage using a trailing comma for + the last item in the array; this minimizes the impact of adding new items on + successive lines, and helps to ensure no parse errors occur due to a missing + comma. +

+
+
+ +

Classes

+ + +

Class Declaration

+ + +

+ Classes must be named according to Zend Framework's naming conventions. +

+ +

+ The brace should always be written on the line underneath the class name. +

+ +

+ Every class must have a documentation block that conforms to the PHPDocumentor + standard. +

+ +

+ All code in a class must be indented with four spaces. +

+ +

+ Only one class is permitted in each PHP file. +

+ +

+ Placing additional code in class files is permitted but discouraged. + In such files, two blank lines must separate the class from any additional + PHP code in the class file. +

+ +

+ The following is an example of an acceptable class declaration: +

+ +
  1. /**
    2. +
  2. * Documentation Block Here
    3. +
  3. */
    4. +
  4. class SampleClass
    5. +
  5. {
    6. +
  6.     // all contents of class
    7. +
  7.     // must be indented four spaces
    8. +
  8. }
+ + +

+ Classes that extend other classes or which implement interfaces should + declare their dependencies on the same line when possible. +

+ +
  1. class SampleClass extends FooAbstract implements BarInterface
    2. +
  2. {
    3. +
  3. }
+ + +

+ If as a result of such declarations, the line length exceeds the maximum line + length, break the line before the "extends" and/or "implements" + keywords, and pad those lines by one indentation level. +

+ +
  1. class SampleClass
    2. +
  2.     extends FooAbstract
    3. +
  3.     implements BarInterface
    4. +
  4. {
    5. +
  5. }
+ + +

+ If the class implements multiple interfaces and the declaration exceeds the + maximum line length, break after each comma separating the interfaces, and + indent the interface names such that they align. +

+ +
  1. class SampleClass
    2. +
  2.     implements BarInterface,
    3. +
  3.                BazInterface
    4. +
  4. {
    5. +
  5. }
+ +
+ +

Class Member Variables

+ + +

+ Member variables must be named according to Zend Framework's variable naming + conventions. +

+ +

+ Any variables declared in a class must be listed at the top of the class, above + the declaration of any methods. +

+ +

+ The var construct is not permitted. Member variables always + declare their visibility by using one of the private, + protected, or public modifiers. Giving + access to member variables directly by declaring them as public is permitted but + discouraged in favor of accessor methods (set & get). +

+
+
+ +

Functions and Methods

+ + +

Function and Method Declaration

+ + +

+ Functions must be named according to Zend Framework's function naming + conventions. +

+ +

+ Methods inside classes must always declare their visibility by using + one of the private, protected, + or public modifiers. +

+ +

+ As with classes, the brace should always be written on the line underneath the + function name. Space between the function name and the opening parenthesis for + the arguments is not permitted. +

+ +

+ Functions in the global scope are strongly discouraged. +

+ +

+ The following is an example of an acceptable function declaration in a class: +

+ +
  1. /**
    2. +
  2. * Documentation Block Here
    3. +
  3. */
    4. +
  4. class Foo
    5. +
  5. {
    6. +
  6.     /**
    7. +
  7.      * Documentation Block Here
    8. +
  8.      */
    9. +
  9.     public function bar()
    10. +
  10.     {
    11. +
  11.         // all contents of function
    12. +
  12.         // must be indented four spaces
    13. +
  13.     }
    14. +
  14. }
+ + +

+ In cases where the argument list exceeds the maximum line + length, you may introduce line breaks. Additional arguments to the + function or method must be indented one additional level beyond the function + or method declaration. A line break should then occur before the closing + argument paren, which should then be placed on the same line as the opening + brace of the function or method with one space separating the two, and at the + same indentation level as the function or method declaration. The following is + an example of one such situation: +

+ +
  1. /**
    2. +
  2. * Documentation Block Here
    3. +
  3. */
    4. +
  4. class Foo
    5. +
  5. {
    6. +
  6.     /**
    7. +
  7.      * Documentation Block Here
    8. +
  8.      */
    9. +
  9.     public function bar($arg1, $arg2, $arg3,
    10. +
  10.         $arg4, $arg5, $arg6
    11. +
  11.     ) {
    12. +
  12.         // all contents of function
    13. +
  13.         // must be indented four spaces
    14. +
  14.     }
    15. +
  15. }
+ + +

Note: + + Pass-by-reference is the only parameter passing mechanism permitted in a + method declaration. +
+

+ +
  1. /**
    2. +
  2. * Documentation Block Here
    3. +
  3. */
    4. +
  4. class Foo
    5. +
  5. {
    6. +
  6.     /**
    7. +
  7.      * Documentation Block Here
    8. +
  8.      */
    9. +
  9.     public function bar(&$baz)
    10. +
  10.     {}
    11. +
  11. }
+ + +

+ Call-time pass-by-reference is strictly prohibited. +

+ +

+ The return value must not be enclosed in parentheses. This can hinder + readability, in additional to breaking code if a method is later changed to + return by reference. +

+ +
  1. /**
    2. +
  2. * Documentation Block Here
    3. +
  3. */
    4. +
  4. class Foo
    5. +
  5. {
    6. +
  6.     /**
    7. +
  7.      * WRONG
    8. +
  8.      */
    9. +
  9.     public function bar()
    10. +
  10.     {
    11. +
  11.         return($this->bar);
    12. +
  12.     }
    13. +
  13.  
    14. +
  14.     /**
    15. +
  15.      * RIGHT
    16. +
  16.      */
    17. +
  17.     public function bar()
    18. +
  18.     {
    19. +
  19.         return $this->bar;
    20. +
  20.     }
    21. +
  21. }
+ +
+ +

Function and Method Usage

+ + +

+ Function arguments should be separated by a single trailing space after the + comma delimiter. The following is an example of an acceptable invocation of a + function that takes three arguments: +

+ +
  1. threeArguments(1, 2, 3);
+ + +

+ Call-time pass-by-reference is strictly prohibited. See the function + declarations section for the proper way to pass function arguments by-reference. +

+ +

+ In passing arrays as arguments to a function, the function call may include the + "array" hint and may be split into multiple lines to improve readability. In + such cases, the normal guidelines for writing arrays still apply: +

+ +
  1. threeArguments(array(1, 2, 3), 2, 3);
    2. +
  2.  
    3. +
  3. threeArguments(array(1, 2, 3, 'Zend', 'Studio',
    4. +
  4.                      $a, $b, $c,
    5. +
  5.                      56.44, $d, 500), 2, 3);
    6. +
  6.  
    7. +
  7. threeArguments(array(
    8. +
  8.     1, 2, 3, 'Zend', 'Studio',
    9. +
  9.     $a, $b, $c,
    10. +
  10.     56.44, $d, 500
    11. +
  11. ), 2, 3);
+ +
+
+ +

Control Statements

+ + +

If/Else/Elseif

+ + +

+ Control statements based on the if and + elseif constructs must have a single space before the + opening parenthesis of the conditional and a single space after the closing + parenthesis. +

+ +

+ Within the conditional statements between the parentheses, operators must be + separated by spaces for readability. Inner parentheses are encouraged to improve + logical grouping for larger conditional expressions. +

+ +

+ The opening brace is written on the same line as the conditional statement. The + closing brace is always written on its own line. Any content within the braces + must be indented using four spaces. +

+ +
  1. if ($a != 2) {
    2. +
  2.     $a = 2;
    3. +
  3. }
+ + +

+ If the conditional statement causes the line length to exceed the maximum line + length and has several clauses, you may break the conditional into + multiple lines. In such a case, break the line prior to a logic operator, and + pad the line such that it aligns under the first character of the conditional + clause. The closing paren in the conditional will then be placed on a line with + the opening brace, with one space separating the two, at an indentation level + equivalent to the opening control statement. +

+ +
  1. if (($a == $b)
    2. +
  2.     && ($b == $c)
    3. +
  3.     || (Foo::CONST == $d)
    4. +
  4. ) {
    5. +
  5.     $a = $d;
    6. +
  6. }
+ + +

+ The intention of this latter declaration format is to prevent issues when + adding or removing clauses from the conditional during later revisions. +

+ +

+ For "if" statements that include "elseif" or "else", the formatting conventions + are similar to the "if" construct. The following examples demonstrate proper + formatting for "if" statements with "else" and/or "elseif" constructs: +

+ +
  1. if ($a != 2) {
    2. +
  2.     $a = 2;
    3. +
  3. } else {
    4. +
  4.     $a = 7;
    5. +
  5. }
    6. +
  6.  
    7. +
  7. if ($a != 2) {
    8. +
  8.     $a = 2;
    9. +
  9. } elseif ($a == 3) {
    10. +
  10.     $a = 4;
    11. +
  11. } else {
    12. +
  12.     $a = 7;
    13. +
  13. }
    14. +
  14.  
    15. +
  15. if (($a == $b)
    16. +
  16.     && ($b == $c)
    17. +
  17.     || (Foo::CONST == $d)
    18. +
  18. ) {
    19. +
  19.     $a = $d;
    20. +
  20. } elseif (($a != $b)
    21. +
  21.           || ($b != $c)
    22. +
  22. ) {
    23. +
  23.     $a = $c;
    24. +
  24. } else {
    25. +
  25.     $a = $b;
    26. +
  26. }
+ + +

+ PHP allows statements to be written without braces in some + circumstances. This coding standard makes no differentiation- all "if", + "elseif" or "else" statements must use braces. +

+
+ +

Switch

+ + +

+ Control statements written with the "switch" statement must have a single space + before the opening parenthesis of the conditional statement and after the + closing parenthesis. +

+ +

+ All content within the "switch" statement must be indented using four spaces. + Content under each "case" statement must be indented using an additional four + spaces. +

+ +
  1. switch ($numPeople) {
    2. +
  2.     case 1:
    3. +
  3.         break;
    4. +
  4.  
    5. +
  5.     case 2:
    6. +
  6.         break;
    7. +
  7.  
    8. +
  8.     default:
    9. +
  9.         break;
    10. +
  10. }
+ + +

+ The construct default should never be omitted from a + switch statement. +

+ +

Note: + + It is sometimes useful to write a case statement + which falls through to the next case by not including a + break or return within that + case. To distinguish these cases from bugs, any case + statement where break or return + are omitted should contain a comment indicating that the break was + intentionally omitted. +
+

+
+
+ +

Inline Documentation

+ + +

Documentation Format

+ + +

+ All documentation blocks ("docblocks") must be compatible with the phpDocumentor + format. Describing the phpDocumentor format is beyond the scope of this + document. For more information, visit: » http://phpdoc.org/ +

+ +

+ All class files must contain a "file-level" docblock at the top of each file and + a "class-level" docblock immediately above each class. Examples of such + docblocks can be found below. +

+
+ +

Files

+ + +

+ Every file that contains PHP code must have a docblock at + the top of the file that contains these phpDocumentor tags at a minimum: +

+ +
  1. /**
    2. +
  2. * Short description for file
    3. +
  3. *
    4. +
  4. * Long description for file (if any)...
    5. +
  5. *
    6. +
  6. * LICENSE: Some license information
    7. +
  7. *
    8. +
  8. * @category   Zend
    9. +
  9. * @package    Zend_Magic
    10. +
  10. * @subpackage Wand
    11. +
  11. * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
    12. +
  12. * @license    http://framework.zend.com/license   BSD License
    13. +
  13. * @version    $Id:$
    14. +
  14. * @link       http://framework.zend.com/package/PackageName
    15. +
  15. * @since      File available since Release 1.5.0
    16. +
  16. */
+ + +

+ The @category annotation must have a value of "Zend". +

+ +

+ The @package annotation must be assigned, and should be + equivalent to the component name of the class contained in the file; typically, + this will only have two segments, the "Zend" prefix, and the component name. +

+ +

+ The @subpackage annotation is optional. If provided, it + should be the subcomponent name, minus the class prefix. In the example above, + the assumption is that the class in the file is either + "Zend_Magic_Wand", or uses that classname as part of its + prefix. +

+
+ +

Classes

+ + +

+ Every class must have a docblock that contains these phpDocumentor tags at a + minimum: +

+ +
  1. /**
    2. +
  2. * Short description for class
    3. +
  3. *
    4. +
  4. * Long description for class (if any)...
    5. +
  5. *
    6. +
  6. * @category   Zend
    7. +
  7. * @package    Zend_Magic
    8. +
  8. * @subpackage Wand
    9. +
  9. * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
    10. +
  10. * @license    http://framework.zend.com/license   BSD License
    11. +
  11. * @version    Release: @package_version@
    12. +
  12. * @link       http://framework.zend.com/package/PackageName
    13. +
  13. * @since      Class available since Release 1.5.0
    14. +
  14. * @deprecated Class deprecated in Release 2.0.0
    15. +
  15. */
+ + +

+ The @category annotation must have a value of "Zend". +

+ +

+ The @package annotation must be assigned, and should be + equivalent to the component to which the class belongs; typically, this will + only have two segments, the "Zend" prefix, and the component name. +

+ +

+ The @subpackage annotation is optional. If provided, it + should be the subcomponent name, minus the class prefix. In the example above, + the assumption is that the class described is either + "Zend_Magic_Wand", or uses that classname as part of its + prefix. +

+
+ +

Functions

+ + +

+ Every function, including object methods, must have a docblock that contains at + a minimum: +

+ +
    +

  • A description of the function

    • +

  • All of the arguments

    • +

  • All of the possible return values

    • +
+ +

+ It is not necessary to use the "@access" tag because the access level is already + known from the "public", "private", or "protected" modifier used to declare the + function. +

+ +

+ If a function or method may throw an exception, use @throws for all known + exception classes: +

+ +
  1. @throws exceptionclass [description]
+ +
+
+
+
+ + + + + + + + + +
+ Naming Conventions + +
Zend Framework Coding Standard for PHP
+ Programmer's Reference Guide
+ 		+ +
+		 + +
+ + \ No newline at end of file -- cgit v1.2.3