Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History

<h1>Zend Framework 2 Coding Standards</h1>

<h2>TOC</h2>
<ac:macro ac:name="toc"><ac:parameter ac:name="minLevel">2</ac:parameter></ac:macro>

<h2>Overview</h2>

<h3>Scope</h3>

<p>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.</p>

<ac:macro ac:name="note"><ac:rich-text-body>
<p>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 <a href="http://framework.zend.com/license">license</a>.</p></ac:rich-text-body></ac:macro>

<p>Topics covered in Zend Framework's coding standards include:</p>

<ul>
<li>PHP File Formatting</li>
<li>Naming Conventions</li>
<li>Coding Style</li>
<li>Inline Documentation</li>
</ul>

<h3>Goals</h3>

<p>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.</p>

<h3>Conventions</h3>

<p>This document attempts to follow <a href="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>'s verbiage for indicating requirements.</p>

<ul>
<li><strong>MUST</strong> and <strong>MUST NOT</strong> indicate non-optional requirements</li>
<li><strong>SHOULD</strong> and <strong>SHOULD NOT</strong> indicate recommendations for which exceptions may exist</li>
<li><strong>MAY</strong> indicates truly optional requirements</li>
</ul>

<h2>PHP File Formatting</h2>

<h3>General</h3>

<p>For files that contain only PHP code, the closing tag (<code>?></code>) <strong>MUST NOT</strong> be used. It is not required by PHP, and omitting it prevents the accidental injection of trailing white space into the response.</p>

<ac:macro ac:name="warning"><ac:rich-text-body>
<p>Inclusion of arbitrary binary data as permitted by <code>__HALT_COMPILER()</code> <strong>MUST NOT</strong> 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.</p></ac:rich-text-body></ac:macro>

<h3>Indentation</h3>

<p>Indentation <strong>MUST</strong> consist of 4 spaces. Tabs <strong>MUST NOT</strong> be used for indentation.</p>

<h3>Maximum Line Length</h3>

<p>The target line length is 80 characters. That is to say, Zend Framework developers <strong>SHOULD</strong> 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.</p>

<h3>Line Termination</h3>

<p>Line termination follows the Unix text file convention. Lines <strong>MUST</strong> end with a single linefeed (<code>LF</code>) character. Linefeed characters are represented as ordinal 10, or hexadecimal <code>0x0A</code>.</p>

<ac:macro ac:name="note"><ac:rich-text-body>
<p>Do not use carriage returns (<code>CR</code>) as is the convention in Apple OS's (<code>0x0D</code>) or the carriage return - linefeed combination (<code>CRLF</code>) as is standard for the Windows OS (<code>0x0D</code>, <code>0x0A</code>).</p></ac:rich-text-body></ac:macro>

<p>There is one exception to this rule: the last line of a file <strong>MUST NOT</strong> end in a linefeed.</p>

<p>Finally, lines <strong>MUST NOT</strong> have whitespace characters preceding the linefeed character. This is to prevent versioning differences that affect only white characters at line endings.</p>

<h2>Naming Conventions</h2>

<p>Zend Framework standardizes on a class naming convention whereby:</p>

<ul>
<li>Namespaces have a 1:1 relationship to the filesystem.</li>
<li>Classes are stored within the directory determined by the namespace.</li>
</ul>

<p>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.</p>

<h3>Namespaces</h3>

<p>Namespaces <strong>MUST</strong> contain only alphanumeric characters, the underscore, and, of course, the namespace separator (<br class="atl-forced-newline" />).</p>

<p>Namespaces <strong>SHOULD</strong> be MixedCase, and acronyms used in namespaces <strong>SHOULD</strong> as well. As examples:</p>

<ul>
<li>the namespace "Zend\PDF" would not be allowed, while "Zend\Pdf" is acceptable.</li>
<li>the namespace "Zend\XMLRPC" would not be allowed, while "Zend\XmlRpc" is acceptable.</li>
</ul>

<p>Underscores in namespaces have no special meaning, and will not be translated to the directory separator.</p>

<p>Code deployed alongside Zend Framework libraries but which is not part of the Zend Framework standard distribution <strong>SHOULD</strong> utilize separate namespaces.</p>

<h3>Namespace Aliases</h3>

<p>When aliasing within ZF library code, the aliases <strong>SHOULD</strong> typically follow these patterns:</p>

<ul>
<li>If aliasing a namespace, use the final segment of the namespace; this can be accomplished by simply omitting the "as" portion of the alias:
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
use Zend\Filter; // Alias is then "Filter"
use Zend\Form\Element; // Alias is "Element"
]]></ac:plain-text-body></ac:macro></li>
<li>If aliasing a class, either use the class name (no "as" clause), or suffix the class with the subcomponent namespace preceding it:
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
use Zend\Controller\Action\HelperBroker; // aliased as "HelperBroker"
use Zend\Filter\Int as IntFilter; // using suffix
]]></ac:plain-text-body></ac:macro></li>
</ul>

<p>See also the section on "Import Statements" for additional standards related to aliasing and imports.</p>

<h3>Classes</h3>

<p>Class names <strong>MUST</strong> 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</p>

<p>If a class name is comprised of more than one word, the first letter of each new word <strong>MUST</strong> be capitalized. Successive capitalized letters are not allowed, e.g. a class "Zend_PDF" is not allowed while "Zend_Pdf" is acceptable.</p>

<p>See the class names in the standard and extras libraries for examples of this classname convention.</p>

<h3>Abstract Classes</h3>

<p>Abstract classes follow the same conventions as classes, with one additional rule: abstract class names <strong>SHOULD</strong> begin with the term, "Abstract". As examples, "AbstractAdapter" and "AbstractWriter" are both considered valid abstract class names.</p>

<p>Abstract classes <strong>SHOULD</strong> be in the same namespace as concrete implementations. The following would be considered invalid usage:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace Zend\Log;

abstract class AbstractWriter implements Writer
{
}

namespace Zend\Log\Writer;

use Zend\Log\AbstractWriter;

class StreamWriter extends AbstractWriter
{
}
]]></ac:plain-text-body></ac:macro>

<p>While the next example displays proper usage:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace Zend\Log\Writer;

use Zend\Log\Writer;

abstract class AbstractWriter implements Writer
{
}

class StreamWriter extends AbstractWriter
{
}
]]></ac:plain-text-body></ac:macro>

<p>The "Abstract" prefix <strong>MAY</strong> 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:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace Zend\Uri;

abstract class UriFactory
{
public static function factory($uri)

Unknown macro: { // work goes in here... }

}
]]></ac:plain-text-body></ac:macro>

<h3>Interfaces</h3>

<p>Interfaces follow the same conventions as classes, with two additional rules: interface <strong>MUST</strong> be nouns or adjectives and interface class names <strong>SHOULD</strong> end with the term, "Interface". As examples, "ServiceLocationInterface", "EventCollectionInterface", and "PluginLocatorInterface" are all considered appropriate interface names.</p>

<p>Interfaces <strong>MUST</strong> be in the same namespace as concrete implementations.</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace Zend\Log\Writer;

interface class WriterInterface
{
}
]]></ac:plain-text-body></ac:macro>

<h3>Filenames</h3>

<p>All other PHP files <strong>MUST</strong> only use alphanumeric characters, underscores, and the dash character ("-"). Spaces are strictly prohibited.</p>

<p>Any file that contains PHP code <strong>SHOULD</strong> end with the extension ".php", with the notable exception of view scripts. The following examples show acceptable filenames for Zend Framework classes:</p>

<ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
Zend/Db.php

Zend/Controller/Front.php

Zend/View/Helper/FormRadio.php
]]></ac:plain-text-body></ac:macro>

<p>File names <strong>MUST</strong> map to class names as described above.</p>

<h3>Functions and Methods</h3>

<p>Function names <strong>MUST</strong> contain only alphanumeric characters. Underscores are not permitted. Numbers are permitted in function names but are discouraged.</p>

<p>Function names <strong>MUST</strong> always start with a lowercase letter. When a function name consists of more than one word, the first letter of each new word <strong>MUST</strong> be capitalized. This is commonly called "camelCase" formatting.</p>

<p>Verbosity is encouraged. Function names should be as verbose as is practical to fully describe their purpose and behavior.</p>

<p>These are examples of acceptable names for functions:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
filterInput()

getElementById()

widgetFactory()
]]></ac:plain-text-body></ac:macro>

<p>For object-oriented programming, accessors for instance or static variables <strong>SHOULD</strong> be prefixed with "get" or "set". In implementing design patterns, such as the singleton or factory patterns, the name of the method <strong>SHOULD</strong> contain the pattern name where practical to more thoroughly describe behavior.</p>

<p>For methods on objects that are declared with the "private" or "protected" modifier, the first character of the method name <strong>MAY</strong> 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" <strong>SHOULD NOT</strong> contain an underscore.</p>

<p>Functions in the global scope (a.k.a "floating functions") <strong>MAY</strong> be used, but are discouraged. Consider wrapping these functions in a static class, or within a specific namespace.</p>

<h3>Variables</h3>

<p>Variable names <strong>MUST</strong> contain only alphanumeric characters. Underscores are not permitted. Numbers are permitted in variable names but are discouraged in most cases.</p>

<p>For variables that are declared with <code>private</code> or <code>protected</code> visibility, the first character of the variable name <strong>MAY</strong> 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 <code>public</code> visibility <strong>SHOULD NOT</strong> start with an underscore.</p>

<p>As with function names, variable names <strong>MUST</strong> always start with a lowercase letter and follow the "camelCaps" capitalization convention.</p>

<p>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.</p>

<h3>Constants</h3>

<p>Constant names <strong>MAY</strong> contain both alphanumeric characters and underscores.</p>

<p>All letters used in a constant name <strong>MUST</strong> be capitalized, while all words in a constant name <strong>MUST</strong> be separated by underscore characters.</p>

<p>For example, <code>EMBED_SUPPRESS_EMBED_EXCEPTION</code> is permitted but <code>EMBED_SUPPRESSEMBEDEXCEPTION</code> is not.</p>

<p>Constants <strong>MUST</strong> be defined as class members with the "const" modifier. Constants <strong>MAY</strong> be defined in the global scope or within namespaces.</p>

<h2>Coding Style</h2>

<h3>PHP Code Demarcation</h3>

<p>PHP code <strong>MUST</strong> always be delimited by the full-form, standard PHP tags:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
<?php

?>
]]></ac:plain-text-body></ac:macro>

<p>The closing PHP tag (<code>?></code>) <strong>MUST</strong> be omitted if no markup or code follows it.</p>

<p>Short tags <strong>MUST NOT</strong> be used within Zend Framework library code, but <strong>MAY</strong> be used within view scripts.</p>

<h3>Strings</h3>

<h4>String Literals</h4>

<p>When a string is literal (contains no variable substitutions), the apostrophe or "single quote" <strong>SHOULD</strong> be used to demarcate the string:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
$a = 'Example String';
]]></ac:plain-text-body></ac:macro>

<h4>String Literals Containing Apostrophes</h4>

<p>When a literal string itself contains apostrophes, you <strong>MAY</strong> demarcate the string with quotation marks or "double quotes". This is especially useful for SQL statements:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
$sql = "SELECT id, name from people "
. "WHERE name='Fred' OR name='Susan'";
]]></ac:plain-text-body></ac:macro>

<p>This syntax is preferred over escaping apostrophes as it is much easier to read.</p>

<h4>Variable Substitution</h4>

<p>Variable substitution <strong>SHOULD</strong> use either of the folowing forms:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
$greeting = "Hello $name, welcome back!";

$greeting = "Hello {$name}, welcome back!";
]]></ac:plain-text-body></ac:macro>

<p>For consistency, this form <strong>SHOULD NOT</strong> be used:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
$greeting = "Hello $

Unknown macro: {name}

, welcome back!";
]]></ac:plain-text-body></ac:macro>

<h4>String Concatenation</h4>

<p>Strings <strong>MUST</strong> be concatenated using the "." operator. A space <strong>MUST</strong> always be added before and after the "." operator to improve readability:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
$company = 'Zend' . ' ' . 'Technologies';
]]></ac:plain-text-body></ac:macro>

<p>When concatenating strings with the "." operator, one <strong>SHOULD</strong> 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:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
$sql = "SELECT id, name FROM people "
. "WHERE name = 'Susan' "
. "ORDER BY name ASC ";
]]></ac:plain-text-body></ac:macro>

<h4>Class Names In Strings</h4>

<p>When referencing a class name in a string, the fully qualified class name <strong>MUST</strong> be provided, and <strong>MUST NOT</strong> 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".</p>

<h3>Arrays</h3>

<h4>Numerically Indexed Arrays</h4>

<p>When declaring indexed arrays with the <code>array</code> function, a trailing space <strong>MUST</strong> be added after each comma delimiter to improve readability:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
]]></ac:plain-text-body></ac:macro>

<p>It is permitted to declare multi-line indexed arrays using the <code>array</code> construct. In this case, each successive line <strong>MUST</strong> be padded with spaces such that the beginning of each line is aligned with the initial element of the array:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
$a, $b, $c,
56.44, $d, 500);
]]></ac:plain-text-body></ac:macro>

<p>Alternately, the initial array item <strong>MAY</strong> begin on the following line. If so, it <strong>MUST</strong> be padded at one indentation level greater than the line containing the array declaration, and all successive lines <strong>MUST</strong> have the same indentation; the closing paren <strong>MUST</strong> be on a line by itself at the same indentation level as the line containing the array declaration:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
$sampleArray = array(
1, 2, 3, 'Zend', 'Studio',
$a, $b, $c,
56.44, $d, 500,
);
]]></ac:plain-text-body></ac:macro>

<p>When using this latter declaration, you <strong>SHOULD</strong> 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.</p>

<h4>Associative Arrays</h4>

<p>When declaring associative arrays with the <code>array</code> construct, one <strong>SHOULD</strong> break the statement into multiple lines. In this case, each successive line <strong>MUST</strong> be padded with white space such that both the keys and the values are aligned:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
$sampleArray = array('firstKey' => 'firstValue',
'secondKey' => 'secondValue');
]]></ac:plain-text-body></ac:macro>

<p>Alternately, the initial array item <strong>MAY</strong> 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 <strong>MUST</strong> have the same indentation; the closing paren <strong>MUST</strong> be on a line by itself at the same indentation level as the line containing the array declaration. For readability, the various "=>" assignment operators <strong>SHOULD</strong> be padded such that they align.</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
$sampleArray = array(
'firstKey' => 'firstValue',
'secondKey' => 'secondValue',
);
]]></ac:plain-text-body></ac:macro>

<p>When using this latter declaration, one <strong>SHOULD</strong> 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.</p>

<h3>Namespaces</h3>

<h4>Namespace Declaration</h4>

<p>Files <strong>SHOULD</strong> contain a single namespace; composing multiple namespaces in a single file is strongly discouraged.</p>

<p>Namespace declarations <strong>MUST</strong> 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.</p>

<p>Namespace declarations done according to the above <strong>MUST NOT</strong> have any indentation.</p>

<p>In the case that multiple namespace declarations <em>must</em> be placed in the same file, such declarations <strong>MUST</strong> utilize blocks and not single-line declarations. The opening brace <strong>MUST</strong> be placed on the following line at the same level of indentation, and all code within the block <strong>MUST</strong> receive an extra level of indentation. For example, the following is invalid:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace Foo;

// some code...

namespace Bar;

// more code...
]]></ac:plain-text-body></ac:macro>

<p>But the following is correct:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace Foo
{
// some code ...
}

namespace Bar
{
// more code ...
}
]]></ac:plain-text-body></ac:macro>

<h4>Import Statements</h4>

<p>All explicit dependencies used by a class <strong>MUST</strong> be imported. These include classes and interfaces used in method typehints and explicit <code>instanceof</code> type checks, classes directly instantiated, etc. Exceptions include:</p>

<ul>
<li>Code within the current namespace or subnamespaces of the current namespace</li>
<li>Class names that are dynamically resolved (e.g., from a plugin broker)</li>
</ul>

<p>There MUST be one use keyword per declaration.</p>

<p>There MUST be one blank line after the use block.</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
use Zend\Log\Logger;
use Zend\Event\Eventmanager as Events;
use Zend\View\PhpRenderer as View;
]]></ac:plain-text-body></ac:macro>

<p>Additionally, import statements <strong>SHOULD</strong> be in alphabetical order, to make scanning for entries predictable.</p>

<h3>Classes</h3>

<h4>Class Declaration</h4>

<p>Classes <strong>MUST</strong> be named according to Zend Framework's naming conventions.</p>

<p>The brace <strong>MUST</strong> be written on the line underneath the class name, at the same level of indentation as the class declaration.</p>

<p>Every class <strong>MUST</strong> have a documentation block that conforms to the PHPDocumentor standard.</p>

<p>All code in a class <strong>MUST</strong> be indented with four spaces additional to the level of indentation of the class declaration.</p>

<p>PHP files declaring classes <strong>MUST</strong> contain a single PHP class only.</p>

<p>Placing additional code in class files <strong>MAY</strong> be done, but is discouraged. In such files, two blank lines <strong>MUST</strong> separate the class from any additional PHP code in the class file.</p>

<p>The following is an example of an acceptable class declaration:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
/**

  • Documentation Block Here
    */
    class SampleClass
    {
    // all contents of class
    // must be indented four spaces
    }
    ]]></ac:plain-text-body></ac:macro>

<p>Classes that extend other classes or which implement interfaces <strong>SHOULD</strong> declare their dependencies on the same line when possible.</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
class SampleClass extends AbstractFoo implements Bar
{
}
]]></ac:plain-text-body></ac:macro>

<p>If as a result of such declarations, the line length exceeds the maximum line length, break the line after <code>implements</code> keywords, and pad those lines by one indentation level.</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
class SampleClass extends AbstractFoo implements
Bar
{
}
]]></ac:plain-text-body></ac:macro>

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

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
class SampleClass implements
BarInterface,
BazInterface
{
}
]]></ac:plain-text-body></ac:macro>

<h4>Class Member Variables</h4>

<p>Member variables <strong>MUST</strong> be named according to Zend Framework's variable naming conventions.</p>

<p>Any variables declared in a class <strong>MUST</strong> be listed at the top of the class, above the declaration of any methods.</p>

<p>The <code>var</code> construct <strong>MUST NOT</strong> be used. Member variables <strong>MUST</strong> declare their visibility by using one of the <code>private</code>, <code>protected</code>, or <code>public</code> visibility modifiers. Giving access to member variables directly by declaring them as public <strong>MAY</strong> be done, but is discouraged in favor of accessor methods (<code>set</code> &<br />
<code>get</code>).</p>

<h3>Exceptions</h3>

<p>Each component <strong>MUST</strong> have a marker "ExceptionInterface" interface.</p>

<p>Concrete exceptions for a component <strong>MUST</strong> live in an "Exception" subnamespace. Concrete exception classes <strong>MUST</strong> implement the component's Exception interface, and <strong>SHOULD</strong> extend one of PHP's SPL exception types. Concrete exception classes SHOULD be named after the SPL exception type they extend, but <strong>MAY</strong> have a more descriptive name if warranted.</p>

<p>Subcomponents <strong>MAY</strong> define their own Exception marker interface and concrete implementations, following the same rules as at the root component level. The subcomponent exception interface <strong>SHOULD</strong> extend the parent component's exception interface.</p>

<p>As an example:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
/**

  • Component exceptions
    */
    // In Zend/Foo/Exception/ExceptionInterface.php:
    namespace Zend\Foo\Exception;

interface ExceptionInterface
{
}

// In Zend/Foo/Exception/RuntimeException.php
namespace Zend\Foo\Exception;

class RuntimeException extends \RuntimeException implements ExceptionInterface
{
}

// In Zend/Foo/Exception/TripwireException.php
namespace Zend\Foo\Exception;

use RuntimeException;

class TripwireException extends RuntimeException implements ExceptionInterface
{
}

/**

  • Subcomponent exceptions
    */
    // In Zend/Foo/Bar/Exception/ExceptionInterface.php
    namespace Zend\Foo\Bar\Exception;

use Zend\Foo\Exception\ExceptionInterface as FooExceptionInterface;

interface ExceptionInterface extends FooExceptionInterface
{
}

// Subcomponent concrete exception
// In Zend/Foo/Bar/Exception/DomainException.php
namespace Zend\Foo\Bar\Exception;

class DomainException extends \DomainException implements ExceptionInterface
{
}
]]></ac:plain-text-body></ac:macro>

<h4>Using Exceptions</h4>

<p>Concrete exceptions <strong>SHOULD NOT</strong> be imported; instead, either use exception classes within your namespace, or import the Exception namespace you will use.</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace Zend\Foo;

class Bar
{
public function trigger()

Unknown macro: { // Resolves to ZendFooExceptionRuntimeException throw new ExceptionRuntimeException(); }

}

// Explicit importing:

namespace Zend\Foo\Bar;

use Zend\Foo\Exception;

class Baz
{
public function trigger()

}
]]></ac:plain-text-body></ac:macro>

<p>When throwing an exception, you <strong>SHOULD</strong> provide a useful exception message. Such messages <strong>SHOULD</strong> indicate the root cause of an issue, and provide meaningful diagnostics. As an example, you may want to include the following information:</p>

<ul>
<li>The method throwing the exception (<code><em>METHOD</em></code>)</li>
<li>Any parameters that were involved in calculations that led to the exception (often class names or variable types will be sufficient)</li>
</ul>

<p>We recommend using <code>sprintf()</code> to format your exception messages.</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
throw new Exception\InvalidArgumentException(sprintf(
'%s expects a string argument; received "%s"',
_METHOD_,
(is_object($param) ? get_class($param) : gettype($param))
));
]]></ac:plain-text-body></ac:macro>

<h3>Functions and Methods</h3>

<h4>Function and Method Declaration</h4>

<p>Functions <strong>MUST</strong> be named according to Zend Framework's function naming conventions.</p>

<p>Methods inside classes <strong>MUST</strong> always declare their visibility by using one of the <code>private</code>, <code>protected</code>, or <code>public</code> visibility modifiers.</p>

<p>As with classes, the brace <strong>MUST</strong> always be written on the line underneath the function name. Space <strong>MUST NOT</strong> be inserted between the function name and the opening parenthesis for the arguments.</p>

<p>Functions <strong>SHOULD NOT</strong> be declared in the global scope.</p>

<p>The following is an example of an acceptable function declaration in a class:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
/**

  • Documentation Block Here
    */
    class Foo
    {
    /**
  • Documentation Block Here
    */
    public function bar()
    Unknown macro: { // all contents of function // must be indented four spaces }

    }
    ]]></ac:plain-text-body></ac:macro>

    <p>In cases where the argument list exceeds the maximum line length, you <strong>MAY</strong> introduce line breaks. Additional arguments to the function or method <strong>MUST</strong> be indented one additional level beyond the function or method declaration. A line break <strong>MUST</strong> occur before the closing argument paren, which <strong>MUST</strong> 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:</p>

    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    /**

    • Documentation Block Here
      */
      class Foo
      {
      /**
    • Documentation Block Here
      */
      public function bar($arg1, $arg2, $arg3,
      $arg4, $arg5, $arg6
      )

    }
    ]]></ac:plain-text-body></ac:macro>

<ac:macro ac:name="note"><ac:rich-text-body>
<p>Pass-by-reference is the only parameter passing mechanism permitted in a method declaration.</p></ac:rich-text-body></ac:macro>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
/**

  • Documentation Block Here
    */
    class Foo
    {
    /**
  • Documentation Block Here
    */
    public function bar(&$baz)
    {}
    }
    ]]></ac:plain-text-body></ac:macro>

<p>Call-time pass-by-reference <strong>MUST NOT</strong> be used.</p>

<p>The return value <strong>MUST NOT</strong> be enclosed in parentheses. This can hinder readability, in addition to breaking code if a method is later changed to return by reference.</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
/**

  • Documentation Block Here
    */
    class Foo
    {
    /**
  • WRONG
    */
    public function bar()
    Unknown macro: { return($this->bar); }

/**

  • RIGHT
    */
    public function bar()
    Unknown macro: { return $this->bar; }

    }
    ]]></ac:plain-text-body></ac:macro>

<h4>Closure Definitions</h4>

<p>Closure definitions generally follow the same rules as for functions and methods:</p>

<ul>
<li>Space <strong>MUST NOT</strong> be inserted between the "function" keyword and the opening parenthesis for the arguments.</li>
<li>A space <strong>MUST</strong> be added between any "use" statement used in declaration and the opening parenthesis for its arguments.</li>
<li>In cases where the argument list exceeds the maximum line length, you <strong>MAY</strong> introduce line breaks. Additional arguments to the function or method <strong>MUST</strong> be indented one additional level beyond the function or method declaration. A line break <strong>MUST</strong> occur before the closing argument paren, which <strong>MUST</strong> 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.</li>
<li>Call-time pass-by-reference <strong>MUST NOT</strong> be used.</li>
<li>The return value <strong>MUST NOT</strong> be enclosed in parentheses. This can hinder readability, in addition to breaking code if a method is later changed to return by reference.</li>
</ul>

<p>The primary difference is that closures <strong>MUST</strong> retain the initial brace on the same line in which they are defined (not the following line). Code <strong>MUST</strong> be indented one additional level.</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
/**

  • Opening brace:
    */
    $foo = function($x)
    {
    // WRONG
    };

$foo = function($x) {
// RIGHT
};

/**

  • Use statement declaration
    */
    $foo = function($x) use($y) {
    // WRONG
    };

$foo = function($x) use ($y) {
// RIGHT
};

/**

  • Indentation
    */
    $foo = array_map(function($x) {
    // WRONG
    return strtolower($x);
    }, $array);

$foo = array_map(function($x) {
// RIGHT
return strtolower($x);
}, $array);
]]></ac:plain-text-body></ac:macro>

<h4>Function and Method Usage</h4>

<p>Function arguments <strong>MUST</strong> 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:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
threeArguments(1, 2, 3);
]]></ac:plain-text-body></ac:macro>

<p>Call-time pass-by-reference <strong>MUST NOT</strong> be used. See the function declarations section for the proper way to pass function arguments by-reference.</p>

<p>In passing arrays as arguments to a function, the function call <strong>MAY</strong> include the <code>array</code> declaration and <strong>MAY</strong> be split into multiple lines to improve readability. In such cases, the normal guidelines for writing arrays still apply:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
threeArguments(array(1, 2, 3), 2, 3);

threeArguments(array(1, 2, 3, 'Zend', 'Studio',
$a, $b, $c,
56.44, $d, 500), 2, 3);

threeArguments(array(
1, 2, 3, 'Zend', 'Studio',
$a, $b, $c,
56.44, $d, 500
), 2, 3);
]]></ac:plain-text-body></ac:macro>

<h3>Control Statements</h3>

<h4>If/Else/Elseif</h4>

<p>Control statements based on the <code>if</code> and <code>elseif</code> constructs <strong>MUST</strong> have a single space before the opening parenthesis of the conditional and a single space after the closing parenthesis.</p>

<p>Within the conditional statements between the parentheses, operators <strong>MUST</strong> be separated by spaces for readability. Inner parentheses <strong>SHOULD</strong> be used to improve logical grouping for larger conditional expressions.</p>

<p>The opening brace <strong>MUST</strong> be written on the same line as the conditional statement if the conditional statement does not contain a line feed. The closing brace <strong>MUST</strong> be written on its own line. Any content within the braces MUST be indented using four spaces.</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
if ($a != 2) {
$a = 2;
}
]]></ac:plain-text-body></ac:macro>

<p>If the conditional statement causes the line length to exceed the maximum line length and has several clauses, you <strong>MUST</strong> 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.</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
if (($a == $b)
&& ($b == $c)

(Foo::CONST == $d)
) {
$a = $d;
}
]]></ac:plain-text-body></ac:macro>

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

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

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
if ($a != 2) {
$a = 2;
} else {
$a = 7;
}

if ($a != 2) {
$a = 2;
} elseif ($a == 3) {
$a = 4;
} else {
$a = 7;
}

if (($a == $b)
&& ($b == $c)

(Foo::CONST == $d)
) {
$a = $d;
} elseif (($a != $b)
($b != $c)
) {
$a = $c;
} else {
$a = $b;
}
]]></ac:plain-text-body></ac:macro>

<p>PHP allows statements to be written without braces in some circumstances. This coding standard makes no differentiation; all <code>if</code>, <code>elseif</code> or <code>else</code> statements <strong>MUST</strong> use braces.</p>

<h4>Switch</h4>

<p>Control statements written with the <code>switch</code> statement <strong>MUST</strong> have a single space before the opening parenthesis of the conditional statement and after the closing parenthesis.</p>

<p>All content within the <code>switch</code> statement <strong>MUST</strong> be indented using four spaces. Content under each <code>case</code> statement <strong>MUST</strong> be indented using an additional four spaces.</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
switch ($numPeople) {
case 1:
break;

case 2:
break;

default:
break;
}
]]></ac:plain-text-body></ac:macro>

<p>The construct <code>default</code> <strong>MAY</strong> be omitted from a <code>switch</code> statement, but the code MUST contain a comment indicating deliberate omission in such cases.</p>

<ac:macro ac:name="note"><ac:rich-text-body>
<p>It is sometimes useful to write a <code>case</code> statement which falls through to the next case by not including a <code>break</code> or <code>return</code> within that case. To distinguish these cases from bugs, any <code>case</code> statement where <code>break</code> or <code>return</code> are omitted <strong>SHOULD</strong> contain a comment indicating that the <code>break</code> was intentionally omitted if the case statement contains code that would execute. As an example:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
// Makes no sense insert comment after case A and B
switch ($foo) {
case 'a':
case 'b':
case 'c':
$bar = 'baz';
break;
}

// Here it makes sense, because it could be seen as bug
switch ($foo) {
case 'a':
$baz = 'baz';
// break intentionally omitted

case 'b':
case 'c':
$bar = 'baz';
break;
}
]]></ac:plain-text-body></ac:macro></ac:rich-text-body></ac:macro>

<h3>Inline Documentation</h3>

<h4>Documentation Format</h4>

<p>All documentation blocks ("docblocks") <strong>MUST</strong> be compatible with the phpDocumentor format. Describing the phpDocumentor format is beyond the scope of this document. For more information, visit: <a href="http://phpdoc.org/">http://phpdoc.org/</a></p>

<p>All class files <strong>MUST</strong> 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.</p>

<h4>General Notes</h4>

<p>Classes and interfaces referenced by annotations <strong>MUST</strong> follow the same resolution order as PHP. In other words:</p>

<ul>
<li>If the class is in the same namespace, simply refer to the class name without the namespace:
<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
namespace Foo\Component;

class Bar
{
/**

  • Assumes Foo\Component\Baz:
  • @param Baz $baz
    */
    public function doSomething(Baz $baz)
    {
    }
    }
    ]]></ac:plain-text-body></ac:macro></li>
    <li>If the class is in a subnamespace of the current namespace, refer to it relative to the current namespace:
    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    namespace Foo\Component;

class Bar
{
/**

  • Assumes Foo\Component\Adapter\Baz:
  • @param Adapter\Baz $baz
    */
    public function doSomething(Adapter\Baz $baz)
    {
    }
    }
    ]]></ac:plain-text-body></ac:macro></li>
    <li>If the class is imported, either via a namespace or explicit class name, use the name as specified by the import:
    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    namespace Foo\Component;

use Zend\EventManager\EventManager as Events,
Zend\Log;

class Bar
{
/**

  • Assumes Zend\EventManager\EventManager and Zend\Log\Logger:
  • @param Events $events
  • @param Log\Logger $log
    */
    public function doSomething(Events $events, Log\Logger $log)
    {
    }
    }
    ]]></ac:plain-text-body></ac:macro></li>
    <li>If the class is from another namespace, but not explicitly imported, provide a globally resolvable name:
    <ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
    namespace Foo\Component;

class Bar
{
/**

  • Assumes \Zend\EventManager\EventManager:
  • @param \Zend\EventManager\EventManager $events
    */
    public function doSomething(\Zend\EventManager\EventManager $events)
    {
    }
    }
    ]]></ac:plain-text-body></ac:macro></li>
    </ul>

<ac:macro ac:name="note"><ac:rich-text-body>
<p>This last case should rarely happen, primarily since you should be importing any dependencies. One case where it <em>may</em> happen, however, is in <code>@return</code> annotations, as return types might be determined outside the class scope.</p></ac:rich-text-body></ac:macro>

<h4>Files</h4>

<p>Every file that contains PHP code <strong>MUST</strong> have a docblock at the top of the file that contains these phpDocumentor tags at a minimum:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
/**

<h4>Classes</h4>

<p>Every class <strong>MUST</strong> have a docblock that contains these phpDocumentor tags at a minimum:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
/**

  • Short description for class
    *
  • Long description for class (if any)...
    */
    ]]></ac:plain-text-body></ac:macro>

<h4>Functions</h4>

<p>Every function, including object methods, <strong>MUST</strong> have a docblock that contains at a minimum:</p>

<ul>
<li>A description of the function</li>
<li>All of the arguments</li>
<li>All of the possible return values (even "void")</li>
</ul>

<p>It is not necessary to use the <code>@access</code> annotation because the access level is already known from the <code>public</code>, <code>private</code>, or <code>protected</code> visibility modifier used to declare the function.</p>

<p>If a function or method may throw an exception, use <code>@throws</code> for all known exception classes:</p>

<ac:macro ac:name="code"><ac:default-parameter>php</ac:default-parameter><ac:plain-text-body><![CDATA[
@throws exceptionclass [description]
]]></ac:plain-text-body></ac:macro>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.