diff options
| author | Horus3 | 2014-02-24 16:42:14 +0100 |
|---|---|---|
| committer | Horus3 | 2014-02-24 16:42:14 +0100 |
| commit | 06f945f27840b53e57795dadbc38e76f7e11ab1c (patch) | |
| tree | 689d5c7f4ffa15460c7e90f47c6a7dd59ce4e8bd /zend/documentation/manual/core/en/coding-standard.coding-style.html | |
| download | random-06f945f27840b53e57795dadbc38e76f7e11ab1c.tar.gz | |
init
Diffstat (limited to 'zend/documentation/manual/core/en/coding-standard.coding-style.html')
| -rw-r--r-- | zend/documentation/manual/core/en/coding-standard.coding-style.html | 843 |
1 files changed, 843 insertions, 0 deletions
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 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> + <meta http-equiv="content-type" content="text/html; charset=UTF-8"/> + <title>Coding Style - Zend Framework Manual</title> + +</head> +<body> +<table width="100%"> + <tr valign="top"> + <td width="85%"> + <table width="100%"> + <tr> + <td width="25%" style="text-align: left;"> + <a href="coding-standard.naming-conventions.html">Naming Conventions</a> + </td> + + <td width="50%" style="text-align: center;"> + <div class="up"><span class="up"><a href="coding-standard.html">Zend Framework Coding Standard for PHP</a></span><br /> + <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div> + </td> + + <td width="25%" style="text-align: right;"> + <div class="next" style="text-align: right; float: right;"><a href="doc-standard.html">Zend Framework Documentation Standard</a></div> + </td> + </tr> + </table> +<hr /> +<div id="coding-standard.coding-style" class="section"><div class="info"><h1 class="title">Coding Style</h1></div> + + + <div class="section" id="coding-standard.coding-style.php-code-demarcation" name="coding-standard.coding-style.php-code-demarcation"><div class="info"><h1 class="title">PHP Code Demarcation</h1></div> + + + <p class="para"> + <acronym class="acronym">PHP</acronym> code must always be delimited by the full-form, standard + <acronym class="acronym">PHP</acronym> tags: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #000000; font-weight: bold;"><?php</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> </div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #000000; font-weight: bold;">?></span></div></li></ol></div></div></div> + + + <p class="para"> + Short tags are never allowed. For files containing only <acronym class="acronym">PHP</acronym> + code, the closing tag must always be omitted (See <a href="coding-standard.php-file-formatting.html#coding-standard.php-file-formatting.general" class="link">General standards</a>). + </p> + </div> + + <div class="section" id="coding-standard.coding-style.strings" name="coding-standard.coding-style.strings"><div class="info"><h1 class="title">Strings</h1></div> + + + <div class="section" id="coding-standard.coding-style.strings.literals" name="coding-standard.coding-style.strings.literals"><div class="info"><h1 class="title">String Literals</h1></div> + + + <p class="para"> + When a string is literal (contains no variable substitutions), the apostrophe or + "single quote" should always be used to demarcate the string: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #0000ff;">$a</span> = <span style="color: #ff0000;">'Example String'</span>;</div></li></ol></div></div></div> + + </div> + + <div class="section" id="coding-standard.coding-style.strings.literals-containing-apostrophes" name="coding-standard.coding-style.strings.literals-containing-apostrophes"><div class="info"><h1 class="title">String Literals Containing Apostrophes</h1></div> + + + <p class="para"> + 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 <b><tt>SQL</tt></b> statements: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #0000ff;">$sql</span> = <span style="color: #ff0000;">"SELECT `id`, `name` from `people` "</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> . <span style="color: #ff0000;">"WHERE `name`='Fred' OR `name`='Susan'"</span>;</div></li></ol></div></div></div> + + + <p class="para"> + This syntax is preferred over escaping apostrophes as it is much easier to read. + </p> + </div> + + <div class="section" id="coding-standard.coding-style.strings.variable-substitution" name="coding-standard.coding-style.strings.variable-substitution"><div class="info"><h1 class="title">Variable Substitution</h1></div> + + + <p class="para"> + Variable substitution is permitted using either of these forms: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #0000ff;">$greeting</span> = <span style="color: #ff0000;">"Hello $name, welcome back!"</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> </div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #0000ff;">$greeting</span> = <span style="color: #ff0000;">"Hello {$name}, welcome back!"</span>;</div></li></ol></div></div></div> + + + <p class="para"> + For consistency, this form is not permitted: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #0000ff;">$greeting</span> = <span style="color: #ff0000;">"Hello ${name}, welcome back!"</span>;</div></li></ol></div></div></div> + + </div> + + <div class="section" id="coding-standard.coding-style.strings.string-concatenation" name="coding-standard.coding-style.strings.string-concatenation"><div class="info"><h1 class="title">String Concatenation</h1></div> + + + <p class="para"> + Strings must be concatenated using the "." operator. A space must always + be added before and after the "." operator to improve readability: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #0000ff;">$company</span> = <span style="color: #ff0000;">'Zend'</span> . <span style="color: #ff0000;">' '</span> . <span style="color: #ff0000;">'Technologies'</span>;</div></li></ol></div></div></div> + + + <p class="para"> + 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: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #0000ff;">$sql</span> = <span style="color: #ff0000;">"SELECT `id`, `name` FROM `people` "</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> . <span style="color: #ff0000;">"WHERE `name` = 'Susan' "</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> . <span style="color: #ff0000;">"ORDER BY `name` ASC "</span>;</div></li></ol></div></div></div> + + </div> + </div> + + <div class="section" id="coding-standard.coding-style.arrays" name="coding-standard.coding-style.arrays"><div class="info"><h1 class="title">Arrays</h1></div> + + + <div class="section" id="coding-standard.coding-style.arrays.numerically-indexed" name="coding-standard.coding-style.arrays.numerically-indexed"><div class="info"><h1 class="title">Numerically Indexed Arrays</h1></div> + + + <p class="para">Negative numbers are not permitted as indices.</p> + + <p class="para"> + An indexed array may start with any non-negative number, however + all base indices besides 0 are discouraged. + </p> + + <p class="para"> + When declaring indexed arrays with the <span class="type">Array</span> function, a trailing + space must be added after each comma delimiter to improve readability: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #0000ff;">$sampleArray</span> = <a href="http://www.php.net/array"><span style="color: #000066;">array</span></a><span style="color: #66cc66;">(</span><span style="color: #cc66cc;">1</span>, <span style="color: #cc66cc;">2</span>, <span style="color: #cc66cc;">3</span>, <span style="color: #ff0000;">'Zend'</span>, <span style="color: #ff0000;">'Studio'</span><span style="color: #66cc66;">)</span>;</div></li></ol></div></div></div> + + + <p class="para"> + 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: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #0000ff;">$sampleArray</span> = <a href="http://www.php.net/array"><span style="color: #000066;">array</span></a><span style="color: #66cc66;">(</span><span style="color: #cc66cc;">1</span>, <span style="color: #cc66cc;">2</span>, <span style="color: #cc66cc;">3</span>, <span style="color: #ff0000;">'Zend'</span>, <span style="color: #ff0000;">'Studio'</span>,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span>, <span style="color: #0000ff;">$b</span>, <span style="color: #0000ff;">$c</span>,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #cc66cc;">56.44</span>, <span style="color: #0000ff;">$d</span>, <span style="color: #cc66cc;">500</span><span style="color: #66cc66;">)</span>;</div></li></ol></div></div></div> + + + <p class="para"> + 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: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #0000ff;">$sampleArray</span> = <a href="http://www.php.net/array"><span style="color: #000066;">array</span></a><span style="color: #66cc66;">(</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #cc66cc;">1</span>, <span style="color: #cc66cc;">2</span>, <span style="color: #cc66cc;">3</span>, <span style="color: #ff0000;">'Zend'</span>, <span style="color: #ff0000;">'Studio'</span>,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span>, <span style="color: #0000ff;">$b</span>, <span style="color: #0000ff;">$c</span>,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #cc66cc;">56.44</span>, <span style="color: #0000ff;">$d</span>, <span style="color: #cc66cc;">500</span>,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">)</span>;</div></li></ol></div></div></div> + + + <p class="para"> + 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. + </p> + </div> + + <div class="section" id="coding-standard.coding-style.arrays.associative" name="coding-standard.coding-style.arrays.associative"><div class="info"><h1 class="title">Associative Arrays</h1></div> + + + <p class="para"> + When declaring associative arrays with the <span class="type">Array</span> 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: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #0000ff;">$sampleArray</span> = <a href="http://www.php.net/array"><span style="color: #000066;">array</span></a><span style="color: #66cc66;">(</span><span style="color: #ff0000;">'firstKey'</span> => <span style="color: #ff0000;">'firstValue'</span>,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #ff0000;">'secondKey'</span> => <span style="color: #ff0000;">'secondValue'</span><span style="color: #66cc66;">)</span>;</div></li></ol></div></div></div> + + + <p class="para"> + 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. + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #0000ff;">$sampleArray</span> = <a href="http://www.php.net/array"><span style="color: #000066;">array</span></a><span style="color: #66cc66;">(</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #ff0000;">'firstKey'</span> => <span style="color: #ff0000;">'firstValue'</span>,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #ff0000;">'secondKey'</span> => <span style="color: #ff0000;">'secondValue'</span>,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">)</span>;</div></li></ol></div></div></div> + + + <p class="para"> + 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. + </p> + </div> + </div> + + <div class="section" id="coding-standard.coding-style.classes" name="coding-standard.coding-style.classes"><div class="info"><h1 class="title">Classes</h1></div> + + + <div class="section" id="coding-standard.coding-style.classes.declaration" name="coding-standard.coding-style.classes.declaration"><div class="info"><h1 class="title">Class Declaration</h1></div> + + + <p class="para"> + Classes must be named according to Zend Framework's naming conventions. + </p> + + <p class="para"> + The brace should always be written on the line underneath the class name. + </p> + + <p class="para"> + Every class must have a documentation block that conforms to the PHPDocumentor + standard. + </p> + + <p class="para"> + All code in a class must be indented with four spaces. + </p> + + <p class="para"> + Only one class is permitted in each <acronym class="acronym">PHP</acronym> file. + </p> + + <p class="para"> + Placing additional code in class files is permitted but discouraged. + In such files, two blank lines must separate the class from any additional + <acronym class="acronym">PHP</acronym> code in the class file. + </p> + + <p class="para"> + The following is an example of an acceptable class declaration: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;">/**</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * Documentation Block Here</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> */</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #000000; font-weight: bold;">class</span> SampleClass</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #808080; font-style: italic;">// all contents of class</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #808080; font-style: italic;">// must be indented four spaces</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li></ol></div></div></div> + + + <p class="para"> + Classes that extend other classes or which implement interfaces should + declare their dependencies on the same line when possible. + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #000000; font-weight: bold;">class</span> SampleClass <span style="color: #000000; font-weight: bold;">extends</span> FooAbstract implements BarInterface</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li></ol></div></div></div> + + + <p class="para"> + If as a result of such declarations, the line length exceeds the <a href="coding-standard.php-file-formatting.html#coding-standard.php-file-formatting.max-line-length" class="link">maximum line + length</a>, break the line before the "extends" and/or "implements" + keywords, and pad those lines by one indentation level. + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #000000; font-weight: bold;">class</span> SampleClass</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #000000; font-weight: bold;">extends</span> FooAbstract</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> implements BarInterface</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li></ol></div></div></div> + + + <p class="para"> + 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. + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #000000; font-weight: bold;">class</span> SampleClass</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> implements BarInterface,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> BazInterface</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li></ol></div></div></div> + + </div> + + <div class="section" id="coding-standard.coding-style.classes.member-variables" name="coding-standard.coding-style.classes.member-variables"><div class="info"><h1 class="title">Class Member Variables</h1></div> + + + <p class="para"> + Member variables must be named according to Zend Framework's variable naming + conventions. + </p> + + <p class="para"> + Any variables declared in a class must be listed at the top of the class, above + the declaration of any methods. + </p> + + <p class="para"> + The <em class="emphasis">var</em> construct is not permitted. Member variables always + declare their visibility by using one of the <span class="property">private</span>, + <span class="property">protected</span>, or <span class="property">public</span> modifiers. Giving + access to member variables directly by declaring them as public is permitted but + discouraged in favor of accessor methods (set & get). + </p> + </div> + </div> + + <div class="section" id="coding-standard.coding-style.functions-and-methods" name="coding-standard.coding-style.functions-and-methods"><div class="info"><h1 class="title">Functions and Methods</h1></div> + + + <div class="section" id="coding-standard.coding-style.functions-and-methods.declaration" name="coding-standard.coding-style.functions-and-methods.declaration"><div class="info"><h1 class="title">Function and Method Declaration</h1></div> + + + <p class="para"> + Functions must be named according to Zend Framework's function naming + conventions. + </p> + + <p class="para"> + Methods inside classes must always declare their visibility by using + one of the <span class="property">private</span>, <span class="property">protected</span>, + or <span class="property">public</span> modifiers. + </p> + + <p class="para"> + 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. + </p> + + <p class="para"> + Functions in the global scope are strongly discouraged. + </p> + + <p class="para"> + The following is an example of an acceptable function declaration in a class: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;">/**</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * Documentation Block Here</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> */</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #000000; font-weight: bold;">class</span> Foo</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #808080; font-style: italic;">/**</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * Documentation Block Here</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> */</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #000000; font-weight: bold;">public</span> <span style="color: #000000; font-weight: bold;">function</span> bar<span style="color: #66cc66;">(</span><span style="color: #66cc66;">)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #808080; font-style: italic;">// all contents of function</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #808080; font-style: italic;">// must be indented four spaces</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #66cc66;">}</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li></ol></div></div></div> + + + <p class="para"> + In cases where the argument list exceeds the <a href="coding-standard.php-file-formatting.html#coding-standard.php-file-formatting.max-line-length" class="link">maximum line + length</a>, 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: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;">/**</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * Documentation Block Here</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> */</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #000000; font-weight: bold;">class</span> Foo</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #808080; font-style: italic;">/**</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * Documentation Block Here</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> */</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #000000; font-weight: bold;">public</span> <span style="color: #000000; font-weight: bold;">function</span> bar<span style="color: #66cc66;">(</span><span style="color: #0000ff;">$arg1</span>, <span style="color: #0000ff;">$arg2</span>, <span style="color: #0000ff;">$arg3</span>,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$arg4</span>, <span style="color: #0000ff;">$arg5</span>, <span style="color: #0000ff;">$arg6</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #66cc66;">)</span> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #808080; font-style: italic;">// all contents of function</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #808080; font-style: italic;">// must be indented four spaces</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #66cc66;">}</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li></ol></div></div></div> + + + <blockquote><p><b class="note">Note</b>: + + Pass-by-reference is the only parameter passing mechanism permitted in a + method declaration. + <br /> + </p></blockquote> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;">/**</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * Documentation Block Here</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> */</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #000000; font-weight: bold;">class</span> Foo</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #808080; font-style: italic;">/**</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * Documentation Block Here</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> */</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #000000; font-weight: bold;">public</span> <span style="color: #000000; font-weight: bold;">function</span> bar<span style="color: #66cc66;">(</span>&<span style="color: #0000ff;">$baz</span><span style="color: #66cc66;">)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #66cc66;">{</span><span style="color: #66cc66;">}</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li></ol></div></div></div> + + + <p class="para"> + Call-time pass-by-reference is strictly prohibited. + </p> + + <p class="para"> + 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. + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;">/**</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * Documentation Block Here</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> */</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #000000; font-weight: bold;">class</span> Foo</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #808080; font-style: italic;">/**</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * WRONG</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> */</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #000000; font-weight: bold;">public</span> <span style="color: #000000; font-weight: bold;">function</span> bar<span style="color: #66cc66;">(</span><span style="color: #66cc66;">)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #b1b100;">return</span><span style="color: #66cc66;">(</span><span style="color: #0000ff;">$this</span>-><span style="color: #006600;">bar</span><span style="color: #66cc66;">)</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #66cc66;">}</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> </div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #808080; font-style: italic;">/**</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * RIGHT</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> */</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #000000; font-weight: bold;">public</span> <span style="color: #000000; font-weight: bold;">function</span> bar<span style="color: #66cc66;">(</span><span style="color: #66cc66;">)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #b1b100;">return</span> <span style="color: #0000ff;">$this</span>-><span style="color: #006600;">bar</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #66cc66;">}</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li></ol></div></div></div> + + </div> + + <div class="section" id="coding-standard.coding-style.functions-and-methods.usage" name="coding-standard.coding-style.functions-and-methods.usage"><div class="info"><h1 class="title">Function and Method Usage</h1></div> + + + <p class="para"> + 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: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;">threeArguments<span style="color: #66cc66;">(</span><span style="color: #cc66cc;">1</span>, <span style="color: #cc66cc;">2</span>, <span style="color: #cc66cc;">3</span><span style="color: #66cc66;">)</span>;</div></li></ol></div></div></div> + + + <p class="para"> + Call-time pass-by-reference is strictly prohibited. See the function + declarations section for the proper way to pass function arguments by-reference. + </p> + + <p class="para"> + 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: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;">threeArguments<span style="color: #66cc66;">(</span><a href="http://www.php.net/array"><span style="color: #000066;">array</span></a><span style="color: #66cc66;">(</span><span style="color: #cc66cc;">1</span>, <span style="color: #cc66cc;">2</span>, <span style="color: #cc66cc;">3</span><span style="color: #66cc66;">)</span>, <span style="color: #cc66cc;">2</span>, <span style="color: #cc66cc;">3</span><span style="color: #66cc66;">)</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> </div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;">threeArguments<span style="color: #66cc66;">(</span><a href="http://www.php.net/array"><span style="color: #000066;">array</span></a><span style="color: #66cc66;">(</span><span style="color: #cc66cc;">1</span>, <span style="color: #cc66cc;">2</span>, <span style="color: #cc66cc;">3</span>, <span style="color: #ff0000;">'Zend'</span>, <span style="color: #ff0000;">'Studio'</span>,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span>, <span style="color: #0000ff;">$b</span>, <span style="color: #0000ff;">$c</span>,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #cc66cc;">56.44</span>, <span style="color: #0000ff;">$d</span>, <span style="color: #cc66cc;">500</span><span style="color: #66cc66;">)</span>, <span style="color: #cc66cc;">2</span>, <span style="color: #cc66cc;">3</span><span style="color: #66cc66;">)</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> </div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;">threeArguments<span style="color: #66cc66;">(</span><a href="http://www.php.net/array"><span style="color: #000066;">array</span></a><span style="color: #66cc66;">(</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #cc66cc;">1</span>, <span style="color: #cc66cc;">2</span>, <span style="color: #cc66cc;">3</span>, <span style="color: #ff0000;">'Zend'</span>, <span style="color: #ff0000;">'Studio'</span>,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span>, <span style="color: #0000ff;">$b</span>, <span style="color: #0000ff;">$c</span>,</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #cc66cc;">56.44</span>, <span style="color: #0000ff;">$d</span>, <span style="color: #cc66cc;">500</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">)</span>, <span style="color: #cc66cc;">2</span>, <span style="color: #cc66cc;">3</span><span style="color: #66cc66;">)</span>;</div></li></ol></div></div></div> + + </div> + </div> + + <div class="section" id="coding-standard.coding-style.control-statements" name="coding-standard.coding-style.control-statements"><div class="info"><h1 class="title">Control Statements</h1></div> + + + <div class="section" id="coding-standard.coding-style.control-statements.if-else-elseif" name="coding-standard.coding-style.control-statements.if-else-elseif"><div class="info"><h1 class="title">If/Else/Elseif</h1></div> + + + <p class="para"> + Control statements based on the <em class="emphasis">if</em> and + <em class="emphasis">elseif</em> constructs must have a single space before the + opening parenthesis of the conditional and a single space after the closing + parenthesis. + </p> + + <p class="para"> + 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. + </p> + + <p class="para"> + 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. + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #b1b100;">if</span> <span style="color: #66cc66;">(</span><span style="color: #0000ff;">$a</span> != <span style="color: #cc66cc;">2</span><span style="color: #66cc66;">)</span> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span> = <span style="color: #cc66cc;">2</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li></ol></div></div></div> + + + <p class="para"> + If the conditional statement causes the line length to exceed the <a href="coding-standard.php-file-formatting.html#coding-standard.php-file-formatting.max-line-length" class="link">maximum line + length</a> 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. + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #b1b100;">if</span> <span style="color: #66cc66;">(</span><span style="color: #66cc66;">(</span><span style="color: #0000ff;">$a</span> == <span style="color: #0000ff;">$b</span><span style="color: #66cc66;">)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> && <span style="color: #66cc66;">(</span><span style="color: #0000ff;">$b</span> == <span style="color: #0000ff;">$c</span><span style="color: #66cc66;">)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> || <span style="color: #66cc66;">(</span>Foo::<span style="color: #006600;">CONST</span> == <span style="color: #0000ff;">$d</span><span style="color: #66cc66;">)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">)</span> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span> = <span style="color: #0000ff;">$d</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li></ol></div></div></div> + + + <p class="para"> + The intention of this latter declaration format is to prevent issues when + adding or removing clauses from the conditional during later revisions. + </p> + + <p class="para"> + 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: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #b1b100;">if</span> <span style="color: #66cc66;">(</span><span style="color: #0000ff;">$a</span> != <span style="color: #cc66cc;">2</span><span style="color: #66cc66;">)</span> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span> = <span style="color: #cc66cc;">2</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span> <span style="color: #b1b100;">else</span> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span> = <span style="color: #cc66cc;">7</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> </div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #b1b100;">if</span> <span style="color: #66cc66;">(</span><span style="color: #0000ff;">$a</span> != <span style="color: #cc66cc;">2</span><span style="color: #66cc66;">)</span> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span> = <span style="color: #cc66cc;">2</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span> <span style="color: #b1b100;">elseif</span> <span style="color: #66cc66;">(</span><span style="color: #0000ff;">$a</span> == <span style="color: #cc66cc;">3</span><span style="color: #66cc66;">)</span> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span> = <span style="color: #cc66cc;">4</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span> <span style="color: #b1b100;">else</span> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span> = <span style="color: #cc66cc;">7</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> </div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #b1b100;">if</span> <span style="color: #66cc66;">(</span><span style="color: #66cc66;">(</span><span style="color: #0000ff;">$a</span> == <span style="color: #0000ff;">$b</span><span style="color: #66cc66;">)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> && <span style="color: #66cc66;">(</span><span style="color: #0000ff;">$b</span> == <span style="color: #0000ff;">$c</span><span style="color: #66cc66;">)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> || <span style="color: #66cc66;">(</span>Foo::<span style="color: #006600;">CONST</span> == <span style="color: #0000ff;">$d</span><span style="color: #66cc66;">)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">)</span> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span> = <span style="color: #0000ff;">$d</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span> <span style="color: #b1b100;">elseif</span> <span style="color: #66cc66;">(</span><span style="color: #66cc66;">(</span><span style="color: #0000ff;">$a</span> != <span style="color: #0000ff;">$b</span><span style="color: #66cc66;">)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> || <span style="color: #66cc66;">(</span><span style="color: #0000ff;">$b</span> != <span style="color: #0000ff;">$c</span><span style="color: #66cc66;">)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">)</span> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span> = <span style="color: #0000ff;">$c</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span> <span style="color: #b1b100;">else</span> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #0000ff;">$a</span> = <span style="color: #0000ff;">$b</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li></ol></div></div></div> + + + <p class="para"> + <acronym class="acronym">PHP</acronym> 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. + </p> + </div> + + <div class="section" id="coding-standards.coding-style.control-statements.switch" name="coding-standards.coding-style.control-statements.switch"><div class="info"><h1 class="title">Switch</h1></div> + + + <p class="para"> + 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. + </p> + + <p class="para"> + 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. + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #b1b100;">switch</span> <span style="color: #66cc66;">(</span><span style="color: #0000ff;">$numPeople</span><span style="color: #66cc66;">)</span> <span style="color: #66cc66;">{</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #b1b100;">case</span> <span style="color: #cc66cc;">1</span>:</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #b1b100;">break</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> </div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #b1b100;">case</span> <span style="color: #cc66cc;">2</span>:</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #b1b100;">break</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> </div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #000000; font-weight: bold;">default</span>:</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"> <span style="color: #b1b100;">break</span>;</div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #66cc66;">}</span></div></li></ol></div></div></div> + + + <p class="para"> + The construct <span class="property">default</span> should never be omitted from a + <span class="property">switch</span> statement. + </p> + + <blockquote><p><b class="note">Note</b>: + + It is sometimes useful to write a <span class="property">case</span> statement + which falls through to the next case by not including a + <span class="property">break</span> or <span class="property">return</span> within that + case. To distinguish these cases from bugs, any <span class="property">case</span> + statement where <span class="property">break</span> or <span class="property">return</span> + are omitted should contain a comment indicating that the break was + intentionally omitted. + <br /> + </p></blockquote> + </div> + </div> + + <div class="section" id="coding-standards.inline-documentation" name="coding-standards.inline-documentation"><div class="info"><h1 class="title">Inline Documentation</h1></div> + + + <div class="section" id="coding-standards.inline-documentation.documentation-format" name="coding-standards.inline-documentation.documentation-format"><div class="info"><h1 class="title">Documentation Format</h1></div> + + + <p class="para"> + 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: <a href="http://phpdoc.org/" class="link external">» http://phpdoc.org/</a> + </p> + + <p class="para"> + 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. + </p> + </div> + + <div class="section" id="coding-standards.inline-documentation.files" name="coding-standards.inline-documentation.files"><div class="info"><h1 class="title">Files</h1></div> + + + <p class="para"> + Every file that contains <acronym class="acronym">PHP</acronym> code must have a docblock at + the top of the file that contains these phpDocumentor tags at a minimum: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;">/**</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * Short description for file</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> *</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * Long description for file (if any)...</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> *</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * LICENSE: Some license information</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> *</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @category Zend</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @package Zend_Magic</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @subpackage Wand</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @copyright Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @license http://framework.zend.com/license BSD License</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @version $Id:$</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @link http://framework.zend.com/package/PackageName</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @since File available since Release 1.5.0</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;">*/</span></div></li></ol></div></div></div> + + + <p class="para"> + The <span class="property">@category</span> annotation must have a value of "Zend". + </p> + + <p class="para"> + The <span class="property">@package</span> 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. + </p> + + <p class="para"> + The <span class="property">@subpackage</span> 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 + "<span class="classname">Zend_Magic_Wand</span>", or uses that classname as part of its + prefix. + </p> + </div> + + <div class="section" id="coding-standards.inline-documentation.classes" name="coding-standards.inline-documentation.classes"><div class="info"><h1 class="title">Classes</h1></div> + + + <p class="para"> + Every class must have a docblock that contains these phpDocumentor tags at a + minimum: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;">/**</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * Short description for class</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> *</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * Long description for class (if any)...</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> *</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @category Zend</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @package Zend_Magic</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @subpackage Wand</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @copyright Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @license http://framework.zend.com/license BSD License</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @version Release: @package_version@</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @link http://framework.zend.com/package/PackageName</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @since Class available since Release 1.5.0</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> * @deprecated Class deprecated in Release 2.0.0</span></div></li> +<li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;"><span style="color: #808080; font-style: italic;"> */</span></div></li></ol></div></div></div> + + + <p class="para"> + The <span class="property">@category</span> annotation must have a value of "Zend". + </p> + + <p class="para"> + The <span class="property">@package</span> 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. + </p> + + <p class="para"> + The <span class="property">@subpackage</span> 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 + "<span class="classname">Zend_Magic_Wand</span>", or uses that classname as part of its + prefix. + </p> + </div> + + <div class="section" id="coding-standards.inline-documentation.functions" name="coding-standards.inline-documentation.functions"><div class="info"><h1 class="title">Functions</h1></div> + + + <p class="para"> + Every function, including object methods, must have a docblock that contains at + a minimum: + </p> + + <ul class="itemizedlist"> + <li class="listitem"><p class="para">A description of the function</p></li> + <li class="listitem"><p class="para">All of the arguments</p></li> + <li class="listitem"><p class="para">All of the possible return values</p></li> + </ul> + + <p class="para"> + 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. + </p> + + <p class="para"> + If a function or method may throw an exception, use @throws for all known + exception classes: + </p> + + <div class="programlisting php"><div class="phpcode"><div class="php" style="font-family: monospace;"><ol><li style="font-family: 'Courier New', Courier, monospace; color: black; font-weight: normal; font-style: normal;"><div style="font-family: 'Courier New', Courier, monospace; font-weight: normal;">@throws exceptionclass <span style="color: #66cc66;">[</span>description<span style="color: #66cc66;">]</span></div></li></ol></div></div></div> + + </div> + </div> + </div> + <hr /> + + <table width="100%"> + <tr> + <td width="25%" style="text-align: left;"> + <a href="coding-standard.naming-conventions.html">Naming Conventions</a> + </td> + + <td width="50%" style="text-align: center;"> + <div class="up"><span class="up"><a href="coding-standard.html">Zend Framework Coding Standard for PHP</a></span><br /> + <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div> + </td> + + <td width="25%" style="text-align: right;"> + <div class="next" style="text-align: right; float: right;"><a href="doc-standard.html">Zend Framework Documentation Standard</a></div> + </td> + </tr> + </table> +</td> + <td style="font-size: smaller;" width="15%"> <style type="text/css"> +#leftbar { + float: left; + width: 186px; + padding: 5px; + font-size: smaller; +} +ul.toc { + margin: 0px 5px 5px 5px; + padding: 0px; +} +ul.toc li { + font-size: 85%; + margin: 1px 0 1px 1px; + padding: 1px 0 1px 11px; + list-style-type: none; + background-repeat: no-repeat; + background-position: center left; +} +ul.toc li.header { + font-size: 115%; + padding: 5px 0px 5px 11px; + border-bottom: 1px solid #cccccc; + margin-bottom: 5px; +} +ul.toc li.active { + font-weight: bold; +} +ul.toc li a { + text-decoration: none; +} +ul.toc li a:hover { + text-decoration: underline; +} +</style> + <ul class="toc"> + <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li> + <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li> + <li class="header up"><a href="coding-standard.html">Zend Framework Coding Standard for PHP</a></li> + <li><a href="coding-standard.overview.html">Overview</a></li> + <li><a href="coding-standard.php-file-formatting.html">PHP File Formatting</a></li> + <li><a href="coding-standard.naming-conventions.html">Naming Conventions</a></li> + <li class="active"><a href="coding-standard.coding-style.html">Coding Style</a></li> + </ul> + </td> + </tr> +</table> +</body> +</html>
\ No newline at end of file |