Dev.Coding Standard PHP Pi

Selected PHP Coding Standard for Pi Engine

Check full version for details.

Files

• Indentation MUST consist of 4 spaces, not tabs.
• Maximum line length is 80 characters, no exceeding of 120 characters.
• All PHP files MUST use the Unix LF (linefeed) line ending.
• All PHP files MUST end with a single blank line.
• The closing ?> tag MUST be omitted from files containing only PHP.

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!";.

Alignments

• 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 ";

• 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',
);

• 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');

• Namespaces and classes with multi-line implements keywords, pad those lines by one indentation level.

class ClassName extends ParentClass implements
    \ArrayAccess,
    \Countable,
    \Serializable
{
    // constants, properties, methods
}

• Function/method definition with multi-line argument list with first element on new line: the first item in the list MUST be on the next line, and there MUST be only one interface per line.

class ClassName
{
    public function aVeryLongMethodName(
        ClassTypeHint $arg1,
        &$arg2,
        array $arg3 = []
    ) {
        // method body
    }
}

• Function/method definition with multi-line argument list with first element on the same line

class Foo
{
    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]