Dev.Coding Standard PHP Pi

Selected PHP Coding Standard for Pi Engine

Check full version for details.

Files

• Omit the closing tag ?> for files containing only PHP code.

• Indentation MUST consist of 4 spaces, not tabs.

• Maximum line length is 80 characters, no exceeding of 120 characters.

• Line termination use Unix convention with single Linefeed (LF), not CR or CRLF.

• Lines MUST NOT have whitespace characters preceding the LF character.

• Files MUST have a single extra blank line at the bottom.

Naming conventions

• Successive capitalized letters are not allowed in namespaces and classes.

• Abstract class names SHOULD begin with the term Abstract.

• Interface MUST be nouns or adjectives and interface class names SHOULD end with the term Interface.

• Spaces are strictly prohibited in file names.

• Function/method names MUST contain only alphanumeric characters. Underscores are not permitted.

• Function/method names MUST always start with a lowercase letter with "camelCase" formatting.

• Variable names MUST contain only alphanumeric characters. Underscores are not permitted.

• Variable names MUST always start with a lowercase letter with "camelCaps" convention.

• Variables should always be as verbose as practical. Terse variable names such as $i and $n are discouraged and only for a loop less than 20 lines of code.

• Constant names MUST be capitalized, while all words MUST be separated by underscore characters.

PHP Code Demarcation

• Short tags <? ?> MUST NOT be used within Pi code.

Strings

• When a string is literal, the apostrophe or "single quote" SHOULD be used.

• Variable substitution SHOULD use the form $greeting = "Hello ${name}, welcome back!";.

• When concatenating strings with the "." operator, each successive line SHOULD be padded with white space such that the "." operator is aligned under the "=" operator:

$sql = "SELECT {{id}}, {{name}} FROM {{people}} "
     . "WHERE {{name}} = 'Susan' "
     . "ORDER BY {{name}} ASC ";

Arrays

• Multi-line indexed arrays with first element on the same line: each successive line MUST be padded with spaces such that the beginning of each line is aligned with the initial element of the array:

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

$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');

• Multi-line indexed arrays with first element on a new line: it MUST be padded at one indentation level greater than the line containing the array declaration, and all successive lines MUST have the same indentation and use a trailing comma for the last item in the array; the closing paren MUST be on a line by itself at the same indentation level as the line containing the array declaration:

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

$sampleArray = array(
    'firstKey'  => 'firstValue',
    'secondKey' => 'secondValue',
);

Namespaces and classes

• A single empty line is required between a file-level documentation docblock and namespace declaration.

• Every class MUST have a documentation block that conforms to the PHPDocumentor standard.

• For line length exceeds the maximum line length, break the line after implements keywords, and pad those lines by one indentation level.

class SampleClass extends AbstractFoo implements
    Bar
{
}

Function/method defintion

• For argument list exceeds the maximum line length, additional arguments to a function or method MUST be indented one additional level beyond the function or method declaration. A line break MUST occur before the closing argument paren, which MUST be placed on the same line as the opening brace of the function or method with one space separating the two, and at the same indentation level as the function or method declaration.

/**
 * Documentation Block Here
 */
class Foo
{
    /**
     * Documentation Block Here
     */
    public function bar($arg1, $arg2, $arg3,
        $arg4, $arg5, $arg6
    ) {
        // all contents of function
        // must be indented four spaces
    }
}

Closure definitions:

• Space MUST NOT be inserted between the "function" keyword and the opening parenthesis for the arguments.
• A space MUST be added between any "use" statement and the opening parenthesis for its arguments.
• Closures MUST retain the initial brace on the same line in which they are defined.

/**
 * 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);

Function/method usage

• Function arguments MUST be separated by a single trailing space after the comma delimiter.

if, elseif and else

• All if, elseif or else statements MUST use braces.

• if and elseif constructs MUST have a single space before the opening parenthesis and a single space after the closing parenthesis.

• For if and elseif, the opening brace MUST be written on the same line as the conditional statement.

if ($a != 2) {
    $a = 2;
}

• For multi-line if and elseif, 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.

if (($a == $b)
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
}

Switch

• switch statement MUST have a single space before the opening parenthesis and after the closing parenthesis.

• Content under each case statement MUST be indented using an additional four spaces.

switch ($numPeople) {
    case 1:
        break;
 
    case 2:
        break;
 
    default:
        break;
}

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

Inline Documentation

• All documentation blocks ("docblocks") MUST be compatible with the phpDocumentor format.

• All class files MUST contain a "file-level" docblock at the top of each file and a "class-level" docblock immediately above each class.

• "file-level" docblock contains phpDocumentor tags at a minimum:

/**
 * Pi Engine (http://pialog.org/)
 *
 * @link      http://code.pialog.org for the Pi Engine source repository
 * @copyright Copyright (c) Pi Engine (http://pialog.org/)
 * @license   http://www.pialog.org/license.txt New BSD License
 */

• "class-level" docblock contains phpDocumentor tags at a minimum:

/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * Sample code:
 *
 * <code>
 *   $someCodeForUseExample;
 * </code>
 *
 * @author    [Author Name] <[author_email_address]>
 */

• Every function/method MUST have a docblock that contains at a minimum:

  • A description of the function
  • All of the arguments
  • All of the possible return values (even void)

• Use @throws for all known exception classes:

@throws exceptionclass [description]