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

• Numerically indexed arrays with multi-line elements with first element on a new line.

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

• Associative arrays with multi-line elements and first element on a new line: the various "=>" assignment operators SHOULD be padded such that they align, only one element per line.

$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 discouraged

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

• Function/method call with multi-line arguments with first argument on new line: each subsequent lin is indented once, only one argument per line.

$foo->bar(
    $longArgument,
    $longerArgument,
    $muchLongerArgument
);

• Closure definitions:

$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
    // body
};

$longArgs_longVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
   // body
};

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.

• All class files MUST contain a "file-level" docblock at the top:

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

• Every class MUST have a "class-level" docblock containing 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:

    /**
     * Load a service
     *
     * @param string    $name
     * @param array     $options
     * @return Service\AbstractService
     * @throws \Exception
     */
    public function load($name, $options = array())
    {