Repository navigation
PHP Style Guide
Johnny Johnson edited this page Jan 8, 2015
·
3 revisions
The main purpose of this PHP Standard Reference (PSR) is to provide a complete and formal definition of the PHPDoc standard. This PSR deviates from its predecessor, the de-facto PHPDoc Standard associated with phpDocumentor 1.x, to provide support for newer features in the PHP language and to address some of the shortcomings of its predecessor. This is an adaption of the PSR found in GITHUB at: https://github.com/phpDocumentor This document SHALL NOT:
- Describe a standard for implementing annotations via PHPDoc. Although it does offer versatility which makes it possible to create a subsequent PSR based on current practices. See chapter 5.3 for more information on this topic.
- Describe best practices or recommendations for Coding Standards on the application of the PHPDoc standard. This document is limited to a formal specification of syntax and intention.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
-
"PHPDoc" is a section of documentation which provides information on several aspects of a "Structural Element". It is important to note that the PHPDoc and the DocBlock are two separate entities. The DocBlock is the combination of a DocComment, which is a type of comment, and a PHPDoc entity. It is the PHPDoc entity that contains the syntax as described in chapter 5 such as the description and tags.
-
"Structural Element" is a collection of Programming Constructs which SHOULD be preceded by a DocBlock. The collection contains the following constructs:
-
file
-
require(_once)
-
include(_once)
-
class
-
interface
-
trait
-
function (including methods)
-
property
-
constant
-
variables, both local and global scope.
It is RECOMMENDED to precede a "Structural Element" with a DocBlock with its definition and not with each usage. It is common practice to have the DocBlock precede a Structural Element but it MAY also be separated by a an empty line.
Example:
/** @var int $int This is a counter. */ $int = 0; // there should be no docblock here $int++;or
/** * This class acts as an example on where to position a DocBlock. */ class Foo
{ /** @var string|null $title contains a title for the Foo with a max. length of 24 characters */
protected $title = null; /** * Sets a single-line title. *
* @param string $title A text with a maximum of 24 characters. * * @return void
*/ public function setTitle($title) {
// there should be no docblock here $this->title = $title; } }An example of use that falls beyond the scope of this Standard is to document the variable in a foreach explicitly; several IDEs use this information to assist their auto-completion functionality.
This Standard does not cover this specific instance as a foreach statement is not considered to be a "Structural Element" but a Control Flow statement.
/** @var \Sqlite3 $sqlite */ foreach($connections as $sqlite) {
// there should be no docblock here $sqlite->open('/my/database/path'); <...> }- "DocComment" is a special type of comment which MUST
- start with the character sequence
/**followed by a whitespace character - end with
*/and - have zero or more lines in between.
- start with the character sequence
In case a DocComment spans multiple lines then every line MUST start with an asterisk (*) that SHOULD be aligned with the first asterisk of the opening clause. Single line example:
/ * <...> */Multiline example:
/ * * <...> */- "DocBlock" is a "DocComment" containing a single "PHPDoc" structure and represents the basic in-source representation.
- "Tag" is a single piece of meta information regarding a "Structural Element" or a component thereof.
- "Inline PHPDoc" is a "PHPDoc" that is related to a "Tag" instead of a "Structural element". It replaces the description part of the "Tag".
- "Type" is the determination of what type of data is associated with an element. This is commonly used when determining the exact values of arguments, constants, properties and more. See Appendix A for more detailed information about types.
- "Semantic Version" refers to the definition as set in the Semantic Versioning Specification 2.0.0.
- "FQSEN" is an abbreviation for Fully Qualified Structural Element Name. This notation expands on the Fully Qualified Class Name and adds a notation to identify class/interface/trait members and re-apply the principles of the FQCN to Interfaces, Traits, Functions and global Constants. The following notations can be used per type of "Structural Element": Namespace: \My\Space Function: \My\Space\myFunction() Constant: \My\Space\MY_CONSTANT Class:\My\Space\MyClass Interface: \My\Space\MyInterface Trait: \My\Space\MyTrait Method:\My\Space\MyClass::myMethod() Property: \My\Space\MyClass::$my_property Class Constant:\My\Space\MyClass::MY_CONSTANT A FQSEN has the following ABNF definition: FQSEN = fqnn / fqcn / constant / method / property / function fqnn = "" [name] *("" [name]) fqcn = fqnn "" name constant = (fqnn "" / fqcn "::") name method = fqcn "::" name "()" property = fqcn "::$" name function = fqnn "" name "()" name = (ALPHA / "") *(ALPHA / DIGIT / "")
- Basic Principles
- A PHPDoc MUST always be contained in a "DocComment"; the combination of these two is called a "DocBlock".
- A DocBlock MUST directly precede a "Structural Element" An exception to this principle is the File-level DocBlock which MUST be placed at the top of a PHP source code file as the first DocBlock in a file. To prevent ambiguity when a Structural Element comes directly after a File-level DocBlock MUST that element have its own DocBlock in addition to the File-level DocBlock. Example of a valid File-level DocBlock: