Skip to content

Latest commit

 

History

History
1292 lines (1077 loc) · 18 KB

standard.md

File metadata and controls

1292 lines (1077 loc) · 18 KB

DWS Coding Standard

These are the coding "sniffs" enforced by this standard.

Table Of Contents

Arrays

Array Declarations

Array declarations should not have a space between the array keyword and the opening parenthesis. Empty arrays should not have spaces between brackets/parentheses.

Valid:

<?php
$foo = array();

Invalid:

<?php
$foo = array ( );

Arrow Spacing

Double arrows in arrays should be surrounded by 1 space on each side.

Valid:

<?php
$foo = array('x' => 'y');

Invalid:

<?php
$foo = array('x'=>  'y');

Bracket Spacing

When referencing arrays you should not use spaces before or after the opening bracket or before the closing bracket.

Valid:

<?php
$var = $foo['bar'];

Invalid:

<?php
$var = $foo [ 'bar' ];

Comma Spacing

Commas in arrays should be spaced correctly with no whitespace before the comma. Single-line arrays should have exactly 1 space after the comma and multi-line arrays should have nothing but an optional comment on the line after the comma.

Valid:

<?php
$foo = array(1, 2);

Invalid:

<?php
$foo = array(1 ,2);

Multiline Array Indentation

Multi-line arrays should have each line inside the array indented 4 spaces.

Valid:

<?php
$foo = array(
    1,
    2,
);

Invalid:

<?php
$foo = array(
  1,
        2,
    );

Trailing Commas

Single-line arrays should not have trailing commas and multi-line arrays should.

Valid:

<?php
$foo = array(1, 2);
$foo = array(
    1,
    2,
);

Invalid:

<?php
$foo = array(1, 2,);
$foo = array(
    1,
    2
);

Classes

Lowercase Keywords

The php keywords class, interface, extends, implements, abstract, final, var, and const should be lowercase.

Valid:

<?php
class Foo
{
}

Invalid:

<?php
Class Foo
{
}

Self Member Reference

The self keyword should be used instead of the current class name, should be lowercase, and should not have spaces before or after it.

Valid:

<?php
self::foo();

Invalid:

<?php
Self :: foo();

Code Analysis

Empty Statements

Control Structures with empty bodies are not allowed.

Valid:

<?php
if ($test) {
    $var = 1;
}

Invalid:

<?php
if ($test) {
    // do nothing
}

Condition-Only For Loops

For loops that only have a second expression are not allowed as they should be converted to while loops.

Valid:

<?php
while ($test) {
    echo "Hello\n";
}

Invalid:

<?php
for (;$test;) {
    echo "Hello\n";
}

Unconditional If Statements

If statements that always evaluate to true or false should not be used.

Valid:

<?php
if ($test) {
    $var = 1;
}

Invalid:

<?php
if (true) {
    $var = 1;
}

Unnecessary Final Modifiers

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

Valid:

<?php
final class Foo
{
    public function bar()
    {
    }
}

Invalid:

<?php
final class Foo
{
    public final function bar()
    {
    }
}

Useless Overriding Methods

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

Valid:

<?php
public function foo()
{
    return parent::foo() + 1;
}

Invalid:

<?php
public function foo()
{
    return parent::foo();
}

Commenting

Doc Comment Alignment

The asterisks in a phpdoc comment should align.

Valid:

<?php
/**
 * Foobar.
 *
 * @return array baz
 */
function foo()
{
    return array();
}

Invalid:

<?php
/**
  * Foobar.
  *
  * @return array baz
 */
function foo()
{
    return array();
}

Doc Comment Throws Tag

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

Valid:

<?php
/**
 * @throws Exception all the time
 */
function foo()
{
    throw new Exception('Danger!');
}

Invalid:

<?php
/**
 * @return void
 */
function foo()
{
    throw new Exception('Danger!');
}

Inline Comments

Perl style # comments are not allowed.

Valid:

<?php
// A comment.

Invalid:

<?php
# A comment.

Todos

Todos should be resolved.

Invalid:

<?php
// TODO: Fix this!

Control Structures

Control Signatures

Control structures should use a space before the opening parenthesis and brace and the opening brace should be on the same line.

Valid:

<?php
if ($test) {
    $var = 1;
    echo "Hello\n";
}

Invalid:

<?php
if($test)
{
    $var = 1;
    echo "Hello\n";
}

Foreach Loop Declarations

There should be a space between each element of a foreach loop.

Valid:

<?php
foreach ($ar['nested'] as $key => $value) {
    echo "{$key}: {$value}\n";
}

Invalid:

<?php
foreach ( $ar['nested']as$key=>$value ) {
    echo "{$key}: {$value}\n";
}

For Loop Declarations

There should be a space between each condition of a for loop.

Valid:

<?php
for ($i = 0; $i < 5; $i++) {
    echo "Hello\n";
}

Invalid:

<?php
for ( $i = 0 ;$i < 5 ;$i++ ) {
    echo "Hello\n";
}

Lowercase Declarations

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

Valid:

<?php
if ($test) {
    $var = 1;
}

Invalid:

<?php
If ($test) {
    $var = 1;
}

One Line Control Structures

One Line Control structures should use braces.

Valid:

<?php
if ($value === true) {
    echo 3;
}

Invalid:

<?php
if ($value === true)
    echo 3;

Files

Closing Tags

Files should not have closing php tags.

Valid:

<?php
$var = 1;

Invalid:

<?php
$var = 1;
?>

Including Files

The include and require statements should not have parentheses.

Valid:

<?php
require_once 'foo.php';

Invalid:

<?php
require_once('foo.php');

Line Length

Lines should be no longer than 144 characters.

Valid:

<?php
$foobarbazfoobarbazfoobarbaz =
    $arr['foobarbazfoobarbaz']['foobarbazfoobarbaz']['foobarbazfoobarbaz']['foobarbazfoobarbaz']['foobarbazfoobarbaz']['foobarbazfoobarbaz'];

Invalid:

<?php
$foobarbazfoobarbazfoobarbaz = $arr['foobarbazfoobarbaz']['foobarbazfoobarbaz']['foobarbazfoobarbaz']['foobarbazfoobarbaz']['foobarbazfoobarbaz']['foobarbazfoobarbaz'];

Line Endings

Lines should end with "\n" not "\r\n".

Formatting

Multiple Statements

Multiple statements are not allowed on a single line.

Valid:

<?php
$foo = 1;
$bar = 2;

Invalid:

<?php
$foo = 1; $bar = 2;

Space After Casts

Spaces are not allowed after casting operators.

Valid:

<?php
$foo = (string)1;

Invalid:

<?php
$foo = (string) 1;

Functions

Call-Time Pass-By-Reference

Call-time pass-by-reference is not allowed. It should be declared in the function definition.

Valid:

<?php
function foo(&$bar)
{
    $bar++;
}

$baz = 1;
foo($baz);

Invalid:

<?php
function foo($bar)
{
    $bar++;
}

$baz = 1;
foo(&$baz);

Argument Spacing

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

Valid:

<?php
function foo($a, $b = null)
{
}

Invalid:

<?php
function foo($a ,$b=  null)
{
}

Function Signatures

Function calls should not have spaces before the opening or closing parenthesis. The opening parenthesis in a multi-line function call should be the last thing on its line, and the closing parenthesis should be the first non-whitespace character on its line. Multi-line function calls should be indented one level.

Valid:

<?php
$var = foo(
    $bar,
    $baz
);

Invalid:

<?php
$var = foo ($bar,
            $baz
           );

Duplicate Arguments

Duplicate arguments are not allowed to be declared for functions.

Valid:

<?php
function foo($bar, $baz)
{
}

Invalid:

<?php
function foo($bar, $bar)
{
}

Lowercase Keywords

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

Valid:

<?php
function foo()
{
}

Invalid:

<?php
Function foo()
{
}

Opening Braces

The opening brace of a function definition should be on the line following the declaration.

Valid:

<?php
function foo()
{
}

Invalid:

<?php
function foo() {
}

Valid Default Values

Parameters with default values should be last in the function declaration.

Valid:

<?php
function foo($bar, $baz = null)
{
}

Invalid:

<?php
function foo($baz = null, $bar)
{
}

Metrics

Nesting Level

Nesting levels inside functions should not exceed 5.

Invalid:

<?php
function foo($bar, $baz)
{
    if ($bar) {
        if ($baz) {
            if ($bar != $baz) {
                if ($bar < $baz) {
                    if ($bar > 0) {
                        if ($bar % 2) {
                            echo "Hello";
                        }
                    }
                }
            }
        }
    }
}

Naming Conventions

Constructors

A constructor should be named __construct.

Valid:

<?php
class Foo
{
    public function __construct()
    {
    }
}

Invalid:

<?php
class Foo
{
    public function Foo()
    {
    }
}

Uppercase Constants

Any defined constants should be uppercase.

Valid:

<?php
define('MY_CONST', 1);

Invalid:

<?php
define('My_Const', 1);

Valid Class Names

Classes should begin with capital letters.

Valid:

<?php
class Foo
{
}

Invalid:

<?php
class foo
{
}

Valid Variable Names

Variables should be camelCased with the first letter lowercase. Private and protected member variables should begin with an underscore.

Valid:

<?php
$fooBar = 1;

Invalid:

<?php
$Foobar = 1;

PHP

Deprecated Functions

Deprecated functions should not be used.

Invalid:

<?php
$foo = split('a', $bar);

Short Open Tag

The short open tag is not allowed.

Valid:

<?php
$var = 1;

Invalid:

<?
$var = 1;

Forbidden Functions

The functions sizeof and delete should not be used.

Valid:

<?php
$foo = count($bar);

Invalid:

<?php
$foo = sizeof($bar);

Lowercase Constants

The php constants true, false, and null should be used lowercase.

Valid:

<?php
$foo = true;

Invalid:

<?php
$foo = TRUE;

Lowercase Functions

All php builtin functions should be called lowercase.

Valid:

<?php
if (isset($foo)) {
    echo "Hello\n";
}

Invalid:

<?php
if (IsSet($foo)) {
    echo "Hello\n";
}

Silenced Errors

Suppressing errors is not allowed.

Valid:

<?php
if (isset($foo) && $foo) {
    echo "Hello\n";
}

Invalid:

<?php
if (@$foo) {
    echo "Hello\n";
}

Scope

Static This

Static methods should not use $this.

Valid:

<?php
class Foo
{
    static function bar()
    {
        return self::$staticMember;
    }
}

Invalid:

<?php
class Foo
{
    static function bar()
    {
        return $this->staticMember;
    }
}

Consistent Variable Scoping

A variable must be declared first in the highest scope that it will be used.

Valid:

<?php
$value = null;
if ($i < 3) {
    $value = 3;
}
echo $value;

Invalid:

<?php
if ($i < 3) {
    $value = 3;
}
echo $value;

Strings

Echos

Simple strings should not be enclosed in parentheses when being echoed.

Valid:

<?php
echo "Hello\n";

Invalid:

<?php
echo("Hello\n");

Embedded Variables

Embedded variables in strings should be delimited by braces.

Valid:

<?php
$world = 'World';
echo "Hello, {$world}\n";

Invalid:

<?php
echo("Hello, $world\n");

Unnecessary Concatenation

Strings should not be concatenated to other plain strings.

Valid:

<?php
$foo = "Hello, World\n";

Invalid:

<?php
$foo = 'Hello,' . ' ' . "World\n";

Double Quote Usage

Use of double quotes should be warranted.

Valid:

<?php
$world = 'World';
$foo = "Hello, {$world}";

Invalid:

<?php
$foo = "Hello, World";

Whitespace

Casts

Casts should not have whitespace.

Valid:

<?php
$foo = (string)1;

Invalid:

<?php
$foo = ( string )1;

Control Structures

Control structures should not have spaces just inside the parentheses or blank lines inside the block.

Valid:

<?php
if ($test) {
    $foo = 1;
    $bar = 2;
}

Invalid:

<?php
if ( $test ) {

    $foo = 1;
    $bar = 2;

}

Indentation

4 spaces should be used for indentation, not tabs.

Opening and Closing Braces

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

Valid:

<?php
function foo()
{
    echo "Hello\n";
}

Invalid:

<?php
function foo()
{

    echo "Hello\n";
}

Invalid:

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

}

Language Constructs

The php constructs echo, print, return, include, include_once, require, require_once, and new should have one space after them.

Valid:

<?php
echo "Hello\n";

Invalid:

<?php
echo"Hello\n";

Logical Operators

Logical operators should have one space before and after them.

Valid:

<?php
if ($foo && $bar) {
    echo "Hello\n";
}

Invalid:

<?php
if ($foo&&$bar) {
    echo "Hello\n";
}

Object Operators

The object operator should not have any space around it.

Valid:

<?php
$foo->bar();

Invalid:

<?php
$foo -> bar();

Operators

Arithmetic operators should have one space before and after them.

Valid:

<?php
$foo = $bar + 1;

Invalid:

<?php
$foo = $bar+1;

Closing Braces

Closing braces should be indented at the same level as the beginning of the scope.

Valid:

<?php
if ($test) {
    $foo = 1;
    $bar = 2;
}

Invalid:

<?php
if ($test) {
    $foo = 1;
    $bar = 2;
    }

Scope Indentation

Blocks should be indented 4 spaces.

Valid:

<?php
if ($test) {
    $foo = 1;
    $bar = 2;
}

Invalid:

<?php
if ($test) {
        $foo = 1;
        $bar = 2;
}

Scope Keywords

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

Valid:

<?php
static public function foo()
{
}

Invalid:

<?php
static  public  function foo()
{
}

Semicolons

Semicolons should not have spaces before them.

Valid:

<?php
$foo = 1;

Invalid:

<?php
$foo = 1 ;

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:

<?php
$foo = 1;
$bar = 2;

Invalid:

<?php
$foo = 1;


$bar = 2;