Chadicus Coding Standards

Table of Contents

Superfluous Whitespace

There should be no whitespace at the beginning or end of files or at the end of lines. There should also never be 2 blank lines in a row.

Valid: No superfluous whitespace. Invalid: Two consecutive new lines.
<?php
$foo = 1;
$bar = 2;		 $foo = 1;


$bar = 2;

There should be no empty line after the opening brace or before the closing brace of a function, class, or control structure.

Valid: No superfluous whitespace. Invalid: An extra line at beginning or end of function or class.
function foo()
{
    echo "Hello\n";
}		 function foo()
{

    echo "Hello\n";
}

class Foo()
{
    public function bar()
    {
        echo 3;
    }

}

ElseIf and Else Declarations

An if expression with an else branch is never necessary. You can rewrite the conditions in a way that the else is not necessary and the code becomes simpler to read.

Valid: Method returns early to avoid use of else. Invalid: Else statement used.
public function bar($flag)
{
    if ($flag) {
        // perform action in true case
        return;
    } 

    // perform action in false case
}		 public function bar($flag)
{
    if ($flag) {
        // perform action in true case
    } else {
        // perform action in false case
    }
}

Namespace Declarations

There must be one blank line after the namespace declaration.

Valid: One blank line after the namespace declaration. Invalid: No blank line after the namespace declaration.
namespace \Foo\Bar;

use \Baz;		 namespace \Foo\Bar;
use \Baz;

Namespace Declarations

Each use declaration must contain only one namespace and must come after the first namespace declaration. There should be one blank line after the final use statement.

Valid: One use declaration per namespace. Invalid: Multiple namespaces in a use declaration.
use \Foo;
use \Bar;		 use \Foo, \Bar;
Valid: Use statements come after first namespace. Invalid: Namespace declared after use.
namespace \Foo;

use \Bar;		 use \Bar;

namespace \Foo;
Valid: A single blank line after the final use statement. Invalid: No blank line after the final use statement.
use \Foo;
use \Bar;

class Baz
{
}		 use \Foo;
use \Bar;
class Baz
{
}

Method Declarations

Method names should not be prefixed with an underscore to indicate visibility. The static keyword, when present, should come after the visibility declaration, and the final and abstract keywords should come before.

Valid: Correct method naming. Invalid: An underscore prefix used to indicate visibility.
class Foo
{
    private function bar()
    {
    }
}		 class Foo
{
    private function _bar()
    {
    }
}
Valid: Correct ordering of method prefixes. Invalid: static keyword used before visibility and final used after.
class Foo
{
    final public static function bar()
    {
    }
}		 class Foo
{
    static public final function bar()
    {
    }
}

Class Declarations

There should be exactly 1 space between the abstract or final keyword and the class keyword and between the class keyword and the class name. The extends and implements keywords, if present, must be on the same line as the class name. When interfaces implemented are spread over multiple lines, there should be exactly 1 interface mentioned per line indented by 1 level. The closing brace of the class must go on the first line after the body of the class and must be on a line by itself.

Valid: Correct spacing around class keyword. Invalid: 2 spaces used around class keyword.
abstract class Foo
{
}		 abstract  class  Foo
{
}

Property Declarations

Property names should not be prefixed with an underscore to indicate visibility. Visibility should be used to declare properties rather than the var keyword. Only one property should be declared within a statement.

Valid: Correct property naming. Invalid: An underscore prefix used to indicate visibility.
class Foo
{
    private $bar;
}		 class Foo
{
    private $_bar;
}
Valid: Visibility of property declared. Invalid: Var keyword used to declare property.
class Foo
{
    private $bar;
}		 class Foo
{
    var $bar;
}
Valid: One property declared per statement. Invalid: Multiple properties declared in one statement.
class Foo
{
    private $bar;
    private $baz;
}		 class Foo
{
    private $bar, $baz;
}

Elseif Declarations

PHP's elseif keyword should be used instead of else if.

Valid: Single word elseif keyword used. Invalid: Separate else and if keywords used.
if ($foo) {
    $var = 1;
} elseif ($bar) {
    $var = 2;
}		 if ($foo) {
    $var = 1;
} else if ($bar) {
    $var = 2;
}

Switch Declarations

Case statements should be indented 4 spaces from the switch keyword. It should also be followed by a space. Colons in switch declarations should not be preceded by whitespace. Break statements should be indented 4 more spaces from the case statement. There must be a comment when falling through from one case into the next.

Valid: Case statement indented correctly. Invalid: Case statement not indented 4 spaces.
switch ($foo) {
    case 'bar':
        break;
}		 switch ($foo) {
case 'bar':
    break;
}
Valid: Case statement followed by 1 space. Invalid: Case statement not followed by 1 space.
switch ($foo) {
    case 'bar':
        break;
}		 switch ($foo) {
    case'bar':
        break;
}
Valid: Colons not prefixed by whitespace. Invalid: Colons prefixed by whitespace.
switch ($foo) {
    case 'bar':
        break;
    default:
        break;
}		 switch ($foo) {
    case 'bar' :
        break;
    default :
        break;
}
Valid: Break statement indented correctly. Invalid: Break statement not indented 4 spaces.
switch ($foo) {
    case 'bar':
        break;
}		 switch ($foo) {
    case 'bar':
    break;
}
Valid: Comment marking intentional fall-through. Invalid: No comment marking intentional fall-through.
switch ($foo) {
    case 'bar':
    // no break
    default:
        break;
}		 switch ($foo) {
    case 'bar':
    default:
        break;
}

Control Structure Spacing

Control Structures should have 0 spaces after opening parentheses and 0 spaces before closing parentheses.

Valid: Correct spacing. Invalid: Whitespace used inside the parentheses.
if ($foo) {
    $var = 1;
}		 if ( $foo ) {
    $var = 1;
}

End File Newline

PHP Files should end with exactly one newline.

Class Declaration

Each class must be in a file by itself and must be under a namespace (a top-level vendor name).

Valid: One class in a file. Invalid: Multiple classes in a single file.
<?php
namespace Foo;

class Bar {
}		 <?php
namespace Foo;

class Bar {
}

class Baz {
}
Valid: A vendor-level namespace is used. Invalid: No namespace used in file.
<?php
namespace Foo;

class Bar {
}		 <?php
class Bar {
}

Side Effects

A php file should either contain declarations with no side effects, or should just have logic (including side effects) with no declarations.

Valid: A class defined in a file by itself. Invalid: A class defined in a file with other code.
<?php
class Foo
{
}		 <?php
class Foo
{
}

echo "Class Foo loaded."

PHP Code Tags

Always use <?php ?> to delimit PHP code, not the <? ?> shorthand. This is the most portable way to include PHP code on differing operating systems and setups.

Byte Order Marks

Byte Order Marks that may corrupt your application should not be used. These include 0xefbbbf (UTF-8), 0xfeff (UTF-16 BE) and 0xfffe (UTF-16 LE).

Constant Names

Constants should always be all-uppercase, with underscores to separate words.

Valid: all uppercase Invalid: mixed case
define('FOO_CONSTANT', 'foo');

class FooClass
{
    const FOO_CONSTANT = 'foo';
}		 define('Foo_Constant', 'foo');

class FooClass
{
    const foo_constant = 'foo';
}

Line Endings

Unix-style line endings are preferred ("\n" instead of "\r\n").

Line Length

It is recommended to keep lines at approximately 80 characters long for better code readability.

Multiple Statements On a Single Line

Multiple statements are not allowed on a single line.

Valid: Two statements are spread out on two separate lines. Invalid: Two statements are combined onto one line.
$foo = 1;
$bar = 2;		 $foo = 1; $bar = 2;

Scope Indentation

Indentation for control structures, classes, and functions should be 4 spaces per level.

Valid: 4 spaces are used to indent a control structure. Invalid: 8 spaces are used to indent a control structure.
if ($test) {
    $var = 1;
}		 if ($test) {
        $var = 1;
}

No Tab Indentation

Spaces should be used for indentation instead of tabs.

Lowercase Keywords

All PHP keywords should be lowercase.

Valid: Lowercase array keyword used. Invalid: Non-lowercase array keyword used.
$foo = array(); $foo = Array();

PHP Constants

The true, false and null constants must always be lowercase.

Valid: lowercase constants Invalid: uppercase constants
if ($var === false || $var === null) {
    $var = true;
}		 if ($var === FALSE || $var === NULL) {
    $var = TRUE;
}

Scope Keyword Spacing

The php keywords static, public, private, and protected should have one space after them.

Valid: A single space following the keywords. Invalid: Multiple spaces following the keywords.
public static function foo()
{
}		 public  static  function foo()
{
}

Lowercase Function Keywords

The php keywords function, public, private, protected, and static should be lowercase.

Valid: Lowercase function keyword. Invalid: Uppercase function keyword.
function foo()
{
    return true;
}		 FUNCTION foo()
{
    return true;
}

Default Values in Function Declarations

Arguments with default values go at the end of the argument list.

Valid: argument with default value at end of declaration Invalid: argument with default value at start of declaration
function connect($dsn, $persistent = false)
{
    ...
}		 function connect($persistent = false, $dsn)
{
    ...
}

Function Argument Spacing

Function arguments should have one space after a comma, and single spaces surrounding the equals sign for default values.

Valid: Single spaces after a comma. Invalid: No spaces after a comma.
function foo($bar, $baz)
{
}		 function foo($bar,$baz)
{
}
Valid: Single spaces around an equals sign in function declaration. Invalid: No spaces around an equals sign in function declaration.
function foo($bar, $baz = true)
{
}		 function foo($bar, $baz=true)
{
}

Foreach Loop Declarations

There should be a space between each element of a foreach loop and the as keyword should be lowercase.

Valid: Correct spacing used. Invalid: Invalid spacing used.
foreach ($foo as $bar => $baz) {
    echo $baz;
}		 foreach ( $foo  as  $bar=>$baz ) {
    echo $baz;
}
Valid: Lowercase as keyword. Invalid: Uppercase as keyword.
foreach ($foo as $bar => $baz) {
    echo $baz;
}		 foreach ($foo AS $bar => $baz) {
    echo $baz;
}

For Loop Declarations

In a for loop declaration, there should be no space inside the brackets and there should be 0 spaces before and 1 space after semicolons.

Valid: Correct spacing used. Invalid: Invalid spacing used inside brackets.
for ($i = 0; $i < 10; $i++) {
    echo $i;
}		 for ( $i = 0; $i < 10; $i++ ) {
    echo $i;
}
Valid: Correct spacing used. Invalid: Invalid spacing used before semicolons.
for ($i = 0; $i < 10; $i++) {
    echo $i;
}		 for ($i = 0 ; $i < 10 ; $i++) {
    echo $i;
}
Valid: Correct spacing used. Invalid: Invalid spacing used after semicolons.
for ($i = 0; $i < 10; $i++) {
    echo $i;
}		 for ($i = 0;$i < 10;$i++) {
    echo $i;
}

Lowercase Control Structure Keywords

The php keywords if, else, elseif, foreach, for, do, switch, while, try, and catch should be lowercase.

Valid: Lowercase if keyword. Invalid: Uppercase if keyword.
if ($foo) {
    $bar = true;
}		 IF ($foo) {
    $bar = true;
}

Inline Control Structures

Control Structures should use braces.

Valid: Braces are used around the control structure. Invalid: No braces are used for the control structure..
if ($test) {
    $var = 1;
}		 if ($test)
    $var = 1;

Empty Statements

Control Structures must have at least one statement inside of the body.

Valid: There is a statement inside the control structure. Invalid: The control structure has no statements.
if ($test) {
    $var = 1;
}		 if ($test) {
    // do nothing
}

Condition-Only For Loops

For loops that have only a second expression (the condition) should be converted to while loops.

Valid: A for loop is used with all three expressions. Invalid: A for loop is used without a first or third expression.
for ($i = 0; $i < 10; $i++) {
    echo "{$i}\n";
}		 for (;$test;) {
    $test = doSomething();
}

For Loops With Function Calls in the Test

For loops should not call functions inside the test for the loop when they can be computed beforehand.

Valid: A for loop that determines its end condition before the loop starts. Invalid: A for loop that unnecessarily computes the same value on every iteration.
$end = count($foo);
for ($i = 0; $i < $end; $i++) {
    echo $foo[$i]."\n";
}		 for ($i = 0; $i < count($foo); $i++) {
    echo $foo[$i]."\n";
}

Unconditional If Statements

If statements that are always evaluated should not be used.

Valid: An if statement that only executes conditionally. Invalid: An if statement that is always performed.
if ($test) {
    $var = 1;
}		 if (true) {
    $var = 1;
}
Valid: An if statement that only executes conditionally. Invalid: An if statement that is never performed.
if ($test) {
    $var = 1;
}		 if (false) {
    $var = 1;
}

Unnecessary Final Modifiers

Methods should not be declared final inside of classes that are declared final.

Valid: A method in a final class is not marked final. Invalid: A method in a final class is also marked final.
final class Foo
{
    public function bar()
    {
    }
}		 final class Foo
{
    public final function bar()
    {
    }
}

Useless Overriding Methods

Methods should not be defined that only call the parent method.

Valid: A method that extends functionality on a parent method. Invalid: An overriding method that only calls the parent.
final class Foo
{
    public function bar()
    {
        parent::bar();
        $this->doSomethingElse();
    }
}		 final class Foo
{
    public function bar()
    {
        parent::bar();
    }
}

Doc Comment Alignment

The asterisks in a doc comment should align, and there should be one space between the asterisk and tags.

Valid: Asterisks are aligned. Invalid: Asterisks are not aligned.
/**
 * @see foo()
 */		 /**
  * @see foo()
*/
Valid: One space between asterisk and tag. Invalid: Incorrect spacing used.
/**
 * @see foo()
 */		 /**
 *  @see foo()
 */

Doc Comment Throws Tag

If a function throws any exceptions, they should be documented in a @throws tag.

Valid: @throws tag used. Invalid: No @throws tag used for throwing function.
/**
 * @throws Exception all the time
 * @return void
 */
function foo()
{
    throw new Exception('Danger!');
}		 /**
 * @return void
 */
function foo()
{
    throw new Exception('Danger!');
}

Todo Comments

FIXME Statements should be taken care of.

Valid: A comment without a fixme. Invalid: A fixme comment.
// Handle strange case
if ($test) {
    $var = 1;
}		 // FIXME: This needs to be fixed!
if ($test) {
    $var = 1;
}

Todo Comments

TODO Statements should be taken care of.

Valid: A comment without a todo. Invalid: A todo comment.
// Handle strange case
if ($test) {
    $var = 1;
}		 // TODO: This needs to be fixed!
if ($test) {
    $var = 1;
}

Cyclomatic Complexity

Functions should not have a cyclomatic complexity greater than 20, and should try to stay below a complexity of 10.

Nesting Level

Functions should not have a nesting level greater than 10, and should try to stay below 5.

Documentation generated on Wed, 15 Nov 2017 11:49:32 -0500 by PHP_CodeSniffer 2.8.1