- PHP File Formatting
- Naming Conventions
- Namespace Aliases
- Abstract Classes
- Functions and Methods
- Coding Style
- PHP Code Demarcation
- String Literals
- String Literals Containing Apostrophes
- Variable Substitution
- String Concatenation
- Class Names In Strings
- Functions and Methods
- Control Statements
- Inline Documentation
This document provides guidelines for code formatting and documentation to individuals and teams contributing to Zend Framework. Many developers using Zend Framework have also found these coding standards useful because their code's style remains consistent with all Zend Framework code. It is also worth noting that it requires significant effort to fully specify coding standards.
|Sometimes developers consider the establishment of a standard more important than what that standard actually suggests at the most detailed level of design. The guidelines in Zend Framework's coding standards capture practices that have worked well on the Zend Framework project. You may modify these standards or use them as is in accordance with the terms of our license.|
Topics covered in Zend Framework's coding standards include:
- PHP File Formatting
- Naming Conventions
- Coding Style
- Inline Documentation
Coding standards are important in any development project, but they are particularly important when many developers are working on the same project. Coding standards help ensure that the code is high quality, has fewer bugs, and can be easily maintained.
This document attempts to follow RFC 2119's verbiage for indicating requirements.
- MUST and MUST NOT indicate non-optional requirements
- SHOULD and SHOULD NOT indicate recommendations for which exceptions may exist
- MAY indicates truly optional requirements
For files that contain only PHP code, the closing tag (?>) MUST NOT be used. It is not required by PHP, and omitting it prevents the accidental injection of trailing white space into the response.
|Inclusion of arbitrary binary data as permitted by __HALT_COMPILER() MUST NOT be used in PHP files in the Zend Framework project or files derived from them. Use of this feature is only permitted for some installation scripts.|
Indentation MUST consist of 4 spaces. Tabs MUST NOT be used for indentation.
The target line length is 80 characters. That is to say, Zend Framework developers SHOULD strive keep each line of their code under 80 characters where possible and practical. However, longer lines are acceptable in some circumstances. The maximum length of any line of PHP code is 120 characters.
Line termination follows the Unix text file convention. Lines MUST end with a single linefeed (LF) character. Linefeed characters are represented as ordinal 10, or hexadecimal 0x0A.
|Do not use carriage returns (CR) as is the convention in Apple OS's (0x0D) or the carriage return - linefeed combination (CRLF) as is standard for the Windows OS (0x0D, 0x0A).|
There is one exception to this rule: the last line of a file MUST NOT end in a linefeed.
Finally, lines MUST NOT have whitespace characters preceding the linefeed character. This is to prevent versioning differences that affect only white characters at line endings.
Zend Framework standardizes on a class naming convention whereby:
- Namespaces have a 1:1 relationship to the filesystem.
- Classes are stored within the directory determined by the namespace.
The root directory of a library contains a directory named after the top-level namespace; in the case of Zend Framework, the root directory would be "library/", as it contains the "Zend/" directory, which corresponds to the top-level namespace within the Zend Framework distribution.
Namespaces MUST contain only alphanumeric characters, the underscore, and, of course, the namespace separator (\\).
Namespaces SHOULD be MixedCase, and acronyms used in namespaces SHOULD as well. As examples:
- the namespace "Zend\PDF" would not be allowed, while "Zend\Pdf" is acceptable.
- the namespace "Zend\XMLRPC" would not be allowed, while "Zend\XmlRpc" is acceptable.
Underscores in namespaces have no special meaning, and will not be translated to the directory separator.
Code deployed alongside Zend Framework libraries but which is not part of the Zend Framework standard distribution SHOULD utilize separate namespaces.
When aliasing within ZF library code, the aliases SHOULD typically follow these patterns:
- If aliasing a namespace, use the final segment of the namespace; this can be accomplished by simply omitting the "as" portion of the alias:
- If aliasing a class, either use the class name (no "as" clause), or suffix the class with the subcomponent namespace preceding it:
See also the section on "Import Statements" for additional standards related to aliasing and imports.
Class names MUST contain only alphanumeric characters and the underscore. Numbers are permitted in class names but are discouraged in most cases. Underscores are only permitted in place of the path separator; a class named "Do_Something" would map to the filename "Do/Something.php" (and potentially under a hierarchy named after any
If a class name is comprised of more than one word, the first letter of each new word MUST be capitalized. Successive capitalized letters are not allowed, e.g. a class "Zend_PDF" is not allowed while "Zend_Pdf" is acceptable.
See the class names in the standard and extras libraries for examples of this classname convention.
Abstract classes follow the same conventions as classes, with one additional rule: abstract class names SHOULD begin with the term, "Abstract". As examples, "AbstractAdapter" and "AbstractWriter" are both considered valid abstract class names.
Abstract classes SHOULD be in the same namespace as concrete implementations. The following would be considered invalid usage:
While the next example displays proper usage:
The "Abstract" prefix MAY be omitted from the class name in the case of abstract classes that implement only static functionality, such as factories. As an example, the following is valid usage:
Interfaces follow the same conventions as classes, with two additional rules: interface MUST be nouns or adjectives and interface class names SHOULD end with the term, "Interface". As examples, "ServiceLocationInterface", "EventCollectionInterface", and "PluginLocatorInterface" are all considered appropriate interface names.
Interfaces MUST be in the same namespace as concrete implementations.
All other PHP files MUST only use alphanumeric characters, underscores, and the dash character ("-"). Spaces are strictly prohibited.
Any file that contains PHP code SHOULD end with the extension ".php", with the notable exception of view scripts. The following examples show acceptable filenames for Zend Framework classes:
File names MUST map to class names as described above.
Function names MUST contain only alphanumeric characters. Underscores are not permitted. Numbers are permitted in function names but are discouraged.
Function names MUST always start with a lowercase letter. When a function name consists of more than one word, the first letter of each new word MUST be capitalized. This is commonly called "camelCase" formatting.
Verbosity is encouraged. Function names should be as verbose as is practical to fully describe their purpose and behavior.
These are examples of acceptable names for functions:
For object-oriented programming, accessors for instance or static variables SHOULD be prefixed with "get" or "set". In implementing design patterns, such as the singleton or factory patterns, the name of the method SHOULD contain the pattern name where practical to more thoroughly describe behavior.
For methods on objects that are declared with the "private" or "protected" modifier, the first character of the method name MAY be an underscore. This is the only acceptable application of an underscore in a method name, and is discouraged (as it makes refactoring to public visibility more difficult). Methods declared "public" SHOULD NOT contain an underscore.
Functions in the global scope (a.k.a "floating functions") MAY be used, but are discouraged. Consider wrapping these functions in a static class, or within a specific namespace.
Variable names MUST contain only alphanumeric characters. Underscores are not permitted. Numbers are permitted in variable names but are discouraged in most cases.
For variables that are declared with private or protected visibility, the first character of the variable name MAY be a single underscore. This is the only acceptable application of an underscore in a variable name, and is discouraged (as it makes refactoring to public visibility more difficult). Member variables declared with public visibility SHOULD NOT start with an underscore.
As with function names, variable names MUST always start with a lowercase letter and follow the "camelCaps" capitalization convention.
Verbosity is encouraged. Variables should always be as verbose as practical to describe the data that the developer intends to store in them. Terse variable names such as "$i" and "$n" are discouraged for all but the smallest loop contexts. If a loop contains more than 20 lines of code, the index variables should have more descriptive names.
Constant names MAY contain both alphanumeric characters and underscores.
All letters used in a constant name MUST be capitalized, while all words in a constant name MUST be separated by underscore characters.
For example, EMBED_SUPPRESS_EMBED_EXCEPTION is permitted but EMBED_SUPPRESSEMBEDEXCEPTION is not.
Constants MUST be defined as class members with the "const" modifier. Constants MAY be defined in the global scope or within namespaces.
PHP code MUST always be delimited by the full-form, standard PHP tags:
The closing PHP tag (?>) MUST be omitted if no markup or code follows it.
Short tags MUST NOT be used within Zend Framework library code, but MAY be used within view scripts.
When a string is literal (contains no variable substitutions), the apostrophe or "single quote" SHOULD be used to demarcate the string:
When a literal string itself contains apostrophes, you MAY demarcate the string with quotation marks or "double quotes". This is especially useful for SQL statements:
This syntax is preferred over escaping apostrophes as it is much easier to read.
Variable substitution SHOULD use either of the folowing forms:
For consistency, this form SHOULD NOT be used:
Strings MUST be concatenated using the "." operator. A space MUST always be added before and after the "." operator to improve readability:
When concatenating strings with the "." operator, one SHOULD 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:
When referencing a class name in a string, the fully qualified class name MUST be provided, and MUST NOT include a preceding namespace separator. As an example, if in the namespace "Zend\Log", and referencing the class "StreamWriter" in the "Writer" subnamespace, you would use the string "Zend\Log\Writer\StreamWriter".
When declaring indexed arrays with the array function, a trailing space MUST be added after each comma delimiter to improve readability:
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 the beginning of each line is aligned with the initial element of the array:
Alternately, the initial array item MAY begin on the following line. If so, it MUST be padded at one indentation level greater than the line containing the array declaration, and all successive lines MUST have the same indentation; the closing paren MUST be on a line by itself at the same indentation level as the line containing the array declaration:
When using this latter declaration, you SHOULD use 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.
When declaring associative arrays with the array construct, one SHOULD break the statement into multiple lines. In this case, each successive line MUST be padded with white space such that both the keys and the values are aligned:
Alternately, the initial array item MAY begin on the following line. If so, it MUST be padded at one indentation level greater than the line containing the array declaration, and all successive lines MUST have the same indentation; the closing paren MUST 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.
When using this latter declaration, one SHOULD use 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.
Files SHOULD contain a single namespace; composing multiple namespaces in a single file is strongly discouraged.
Namespace declarations MUST be the first statement in a file, unless multiple namespaces are declared; the only code that should precede the declaration should be a file-level documentation block, with a single empty line between the docblock and the namespace declaration.
Namespace declarations done according to the above MUST NOT have any indentation.
In the case that multiple namespace declarations must be placed in the same file, such declarations MUST utilize blocks and not single-line declarations. The opening brace MUST be placed on the following line at the same level of indentation, and all code within the block MUST receive an extra level of indentation. For example, the following is invalid:
But the following is correct:
All explicit dependencies used by a class MUST be imported. These include classes and interfaces used in method typehints and explicit instanceof type checks, classes directly instantiated, etc. Exceptions include:
- Code within the current namespace or subnamespaces of the current namespace
- Class names that are dynamically resolved (e.g., from a plugin broker)
Import statements MUST be declared once, at the top of the file, following the namespace declaration. The use statement MUST be issued once, with one class (and optional alias) per line, separated by commas and terminated on the last import by a semicolon; class names MUST be aligned:
Additionally, import statements SHOULD be in alphabetical order, to make scanning for entries predictable.
Classes MUST be named according to Zend Framework's naming conventions.
The brace MUST be written on the line underneath the class name, at the same level of indentation as the class declaration.
Every class MUST have a documentation block that conforms to the PHPDocumentor standard.
All code in a class MUST be indented with four spaces additional to the level of indentation of the class declaration.
PHP files declaring classes MUST contain a single PHP class only.
Placing additional code in class files MAY be done, but is 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:
Classes that extend other classes or which implement interfaces SHOULD declare their dependencies on the same line when possible.
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.
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.
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 MUST NOT be used. Member variables MUST declare their visibility by using one of the private, protected, or public visibility modifiers. Giving access to member variables directly by declaring them as public MAY be done, but is discouraged in favor of accessor methods (set &
Each component MUST have a marker "ExceptionInterface" interface.
Concrete exceptions for a component MUST live in an "Exception" subnamespace. Concrete exception classes MUST implement the component's Exception interface, and SHOULD extend one of PHP's SPL exception types. Concrete exception classes SHOULD be named after the SPL exception type they extend, but MAY have a more descriptive name if warranted.
Subcomponents MAY define their own Exception marker interface and concrete implementations, following the same rules as at the root component level. The subcomponent exception interface SHOULD extend the parent component's exception interface.
As an example:
Concrete exceptions SHOULD NOT be imported; instead, either use exception classes within your namespace, or import the Exception namespace you will use.
When throwing an exception, you SHOULD provide a useful exception message. Such messages SHOULD indicate the root cause of an issue, and provide meaningful diagnostics. As an example, you may want to include the following information:
- The method throwing the exception (__METHOD__)
- Any parameters that were involved in calculations that led to the exception (often class names or variable types will be sufficient)
We recommend using sprintf() to format your exception messages.
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 visibility modifiers.
As with classes, the brace MUST always be written on the line underneath the function name. Space MUST NOT be inserted between the function name and the opening parenthesis for the arguments.
Functions SHOULD NOT be declared in the global scope.
The following is an example of an acceptable function declaration in a class:
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 MUST occur before the closing argument paren, which MUST 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:
|Pass-by-reference is the only parameter passing mechanism permitted in a method declaration.|
Call-time pass-by-reference MUST NOT be used.
The return value MUST NOT be enclosed in parentheses. This can hinder readability, in addition to breaking code if a method is later changed to return by reference.
Closure definitions generally follow the same rules as for functions and methods:
- Space MUST NOT be inserted between the "function" keyword and the opening parenthesis for the arguments.
- A space MUST be added between any "use" statement used in declaration and the opening parenthesis for its arguments.
- 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 MUST occur before the closing argument paren, which MUST 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.
- Call-time pass-by-reference MUST NOT be used.
- The return value MUST NOT be enclosed in parentheses. This can hinder readability, in addition to breaking code if a method is later changed to return by reference.
The primary difference is that closures MUST retain the initial brace on the same line in which they are defined (not the following line). Code MUST be indented one additional level.
Function arguments MUST 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:
Call-time pass-by-reference MUST NOT be used. 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 declaration and MAY be split into multiple lines to improve readability. In such cases, the normal guidelines for writing arrays still apply:
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 SHOULD be used to improve logical grouping for larger conditional expressions.
The opening brace MUST be written on the same line as the conditional statement if the conditional statement does not contain a line feed. The closing brace MUST be written on its own line. Any content within the braces MUST be indented using four spaces.
If the conditional statement causes the line length to exceed the maximum line length and has several clauses, you MUST 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.
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:
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.
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.
The construct default MAY be omitted from a switch statement, but the code MUST contain a comment indicating deliberate omission in such cases.
|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 if the case statement contains code that would execute. As an example:|
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.
Classes and interfaces referenced by annotations MUST follow the same resolution order as PHP. In other words:
- If the class is in the same namespace, simply refer to the class name without the namespace:
- If the class is in a subnamespace of the current namespace, refer to it relative to the current namespace:
- If the class is imported, either via a namespace or explicit class name, use the name as specified by the import:
- If the class is from another namespace, but not explicitly imported, provide a globally resolvable name:
|This last case should rarely happen, primarily since you should be importing any dependencies. One case where it may happen, however, is in @return annotations, as return types might be determined outside the class scope.|
Every file that contains PHP code MUST have a docblock at the top of the file that contains these phpDocumentor tags at a minimum:
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. Segments MUST be separated by the underscore ("_") character.
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 lives under that namespace.
Every class MUST have a docblock that contains these phpDocumentor tags at a minimum:
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. Segments MUST be separated by the underscore ("_") character.
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 lives under that namespace.
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 (even "void")
It is not necessary to use the @access annotation because the access level is already known from the public, private, or protected visibility modifier used to declare the function.
If a function or method may throw an exception, use @throws for all known exception classes: