Skip to content

Latest commit

 

History

History
154 lines (132 loc) · 5.45 KB

PHP.md

File metadata and controls

154 lines (132 loc) · 5.45 KB

PHP Standards

  1. All PHP code MUST adhere to the PSR-2 Coding Standard (which MUST follow the PSR-1 Coding Standard).

  2. Short array syntax ([] instead of array()) MUST be used.

  3. Associative arrays SHOULD be formatted without spaces as follows:

       $translations = [
      'and' => 'und',
      'Biotin' => 'Biotine',
      'Calcium' => 'Calcium',
      'Carbohydrate' => 'Koolhydraten'
   ];

    in comparison to with spaces as below

       $translations = [
      'and'          => 'und',
      'Biotin'       => 'Biotine',
      'Calcium'      => 'Calcium',
      'Carbohydrate' => 'Koolhydraten'
   ];

  4. All PHP code MUST adhere to the PSR-4 Autoloading Standard.

  5. Class names MUST be declared in UpperCamelCase.

    1. Acronyms MUST be treated as normal words. HttpException, not HTTPException.

  6. Variable names MUST be declared in camelCase.

    1. Acronyms MUST be treated as normal words. xmlHttpRequest not XMLHTTPRequest.

  7. Scripts MUST be named in camelCase describing their primary function.

  8. Non-static functions MUST NOT be called statically.

  9. Static functions MUST NOT be called non-statically.

  10. Comments SHOULD be used to provide explanation for “why” rather than “how” and SHOULD be used when there isn’t a way to make the code simpler or self-documenting.

  11. Nested ternary operators MUST NOT be used.

  12. PHP file encoding must be UTF-8.

  13. if statements which span multiple lines should be split as follows:

    if ($longVariableNameNumber1
    && $longVariableNameNumber2
    && $longVariableNameNumber3
    && $longVariableNameNumber4
    || $longVariableNameNumber5) {
    // body of control structure
}

  14. There MUST NOT be any assignment or modification of variables in the expressions of if statements.

    if ($response = $request->getResponse()) {
    // not allowed
}

  15. Abstract class names MUST begin with Abstract.

    abstract class AbstractGenerator {
}

  16. Interface names MUST end with Interface.

    interface GeneratorInterface {
}

  17. Class usages SHOULD be in alphabetical order.

    use AbstractClass;
use ExampleInterface;
use Model;

class SomeClassName {}

  18. 'Not' logical operators MUST NOT have whitespace between them and the subject being negated.

    $true = !false;

PHP DocBlock

  1. DocBlock for functions / methods MUST exist where the function / method has arguments or a return value and MUST use the appropriate tags (@param, @return) to denote that. Developers making modifications to a function / method are tasked with ensuring that the DocBlock is up-to-date.

  2. Functions / methods / classes that are sufficiently complex (i.e. not self-documenting) SHOULD have a DocBlock explaining how to use the function / method / class.

  3. DocBlock presenting the type MUST be present for class member variables.

  4. When a description is necessary for class member variables, the DocBlock MUST be multiline:

    class Foo
{
    /** @var int */
    protected $id;

    /**
     * The Bar used to fight the foo
     *
     * @var Bar
     */
    private $bar;
}

  5. DocBlock types for scalar values MUST be one of: bool (not boolean), int (not integer), string, float (not double).

  6. DocBlock types for parameters/return values that are arrays of a single type MUST be written as: Type[]. If the variable is a multi-dimensional array, it MUST be represented with one set of [] per depth (int[][] for an array of array of ints)

  7. If the parameter/return value is an array of several types, it MUST be described in the DocBlock as mixed[].

  8. If the parameter/return value is an array that is sometimes empty, it MUST still be written as in 6) (NOT Type[]|[])

example of a method's DocBlock

/**
 * Foos the bars.
 *
 * @param int   $barId      Some number
 * @param Bar[] $allTheBars Collection of Bar objects
 *
 * @return string[]         List of messages
 */
public function barFooer($barId, array $allTheBars) {}

Open Source

  1. All code MUST adhere to the PSR-2 and PSR-4 standards.
  2. The project MUST at least depend on the lowest supported PHP version and SHOULD depend on the latest fully supported PHP version (see versions).
  3. The vendor name MUST be graze. The vendor namespace MUST be Graze.
  4. The project MUST contain a composer.json file.
    1. It MUST contain:
      1. The name of the project, this MUST match the name of the repository.
      2. The name of the maintainer in the authors section, along with the generic Graze Developers <developers@graze.com> author.
    2. It MUST NOT contain:
      1. The version of the project.
  5. All library code MUST be in a directory named src/.
  6. All tests MUST be a in a directory named tests/.
  7. The project SHOULD use Scrutinizer to check and fix standards and flag code quality issues.
  8. The project MUST be listed on Packagist.