Skip to content

Latest commit

 

History

History
429 lines (348 loc) · 9.9 KB

README.md

File metadata and controls

429 lines (348 loc) · 9.9 KB
Raw

PHP Style Guide

PHP Style Guide to maintain readable code, that looks like it was written by one person, even if a whole team was working on it.

Table of contents

  1. Tabs
  2. Whitespace
  3. Commas
  4. Naming conventions
  5. Classes
  6. Accessors
  7. Strings
  8. Functions
  9. Comparison Operators & Equality
  10. Blocks
  11. Comments

Tabs

  • 1.1 Use soft spaces instead of tabs.
  • 1.2 Use an intendation of 4 spaces.

⬆ back to top

Whitespace

  • 2.1 Place one space before the leading brace.
  class Person {
      public function __contruct() {}
  }
  • 2.2 Place one space before the opening paranthesis in control statements (if, while etc.)
  if ( person->name === 'John Doe' ) {}
  • 2.3 Place no space in between the function name and the opening parenthesis.
  class Person {
      public function __contruct() {}

      /**
       * Walks the line for a given amount of meters.
       *
       * @since 1.0
       * @param int $meters Meters to walk
       * @return void
       */
      public function walkTheLine( $meters ) {
          echo sprintf( 'I am walking the line for %dm.', $meters );
      }
  }
  
  $person = new Person();
  $person->walkTheLine( 500 );
  • 2.4 Set off operators with spaces.
  $x = 1 + 2;
  • 2.5 Use indentation when making long method chains. Use a leading arrow, which emphasizes that the line is a method call, not a new statement.
  $person->walkTheLine()
         ->jump();
  • 2.6 Place one space at the start and one space at the end inside the argument list in function calls and declarations.
  class Person {
      public function __contruct() {}

      /**
       * Walks the line for a given amount of meters.
       *
       * @since 1.0
       * @param int $meters Meters to walk
       * @return void
       */
      public function walkTheLine( $meters ) {
          echo sprintf( 'I am walking the line for %dm.', $meters );
      }
  }
  
  $person->walkTheLine( 500 );
  • 2.7 Place one space at the start and one space at the end inside the braces in control statements (if, while etc.)
  if ( person->name === 'John Doe' ) {
      $person->walkTheLine( 500 );
  }
  • 2.8 Do not allign assignments.
  // Don't do this
  $name   = 'John Doe';
  $age    = 22;
  $region = 'Hessen';
  
  // Correct way
  $name = 'John Doe';
  $age = 22;
  $region = 'Hessen';
  • 2.8 Also not in arrays.
  // Don't do this
  $personProperties = array(
      'name'      => 'John Doe',
      'age'       => 22,
      'region'    => 'Hessen',
  );
  
  // Correct way
  $personProperties = array(
      'name' => 'John Doe',
      'age' => 22,
      'region' => 'Hessen',
  );

⬆ back to top

Commas

  • 3.1 Use trailing commas.
  $numbers = array(
      1,
      2,
      3,
  );
  • 3.2 Use additional trailing commas for the last elements in arrays.
  $numbers = array(
      1,
      2,
      3, // additional trailing comma
  );

⬆ back to top

Naming conventions

  • 4.1 Use camelCase when naming functions and variables.
  $firstName = 'John';
  function createPerson() {}
  • 4.2 Use SNAKE_CASE and uppercase for constants.
  define( 'API_URL', '/api' );
  • 4.3 Use PascalCase when naming classes.
  class SuperHero {
      public function __construct() {}
  }
  • 4.4 Don't use reserved words.
  // bad
  $return = 42;
  
  // good
  $result = 42;

  • 4.5 Place only one class in one file and name the file like the class. Example: Person.php contains a class named Person.

  • 4.6 When file contains no class, use dashes - to seperate words.

⬆ back to top

Classes

  • 5.1 Use arrow notation when accessing properties or methods.
  $person->walkTheLine();
  • 5.2 Use arrow notation and braces {} when accessing properties with a variable.
  $propertyName = 'origin';
  $origin = $person->{$propertyName};
  • 5.3 Always write out property and method visibility.
  // bad
  class Person {
      function __construct() {}
  }
  
  // good
  class Person {
      public function __construct() {}
  }

⬆ back to top

Accessors

  • 6.1 Accessor functions for properties are not required.

  • 6.2 If you do make accessor functions use getVal() and setVal( 'hello' ).

  class Person {
      /**
       * @var string
       */
      private $name = '':
  
      public function __contruct() {}

      /**
       * Setter method for $name property
       *
       * @since 1.0
       * @param string $name Name to assign
       * @return void
       */
      public function setName( $name ) {
          $this->name = $name;
      }
  }
  • 6.3 If the property is a boolean, use isVal() or hasVal().
  if ( $person->hasCoffee() ) {}
  if ( $person->isAlive() ) {}
  • 6.4 It's okay to create magic getter __get and setter __set methods
  class Person {
      /**
       * @var string
       */
      private $name = '':
  
      public function __contruct() {}

      /**
       * Magic getter method for the property passed in $property parameter.
       *
       * @since 1.0
       * @param string $property Property to get
       * @return mixed
       */
      public function __get( $property ) {
          if ( property_exists( $this, $property ) ) {
              return $this->{$property};
          }
      }

      /**
       * Magic setter method for the property passed in $property parameter.
       *
       * @since 1.0
       * @param string $property Property that should be assigned
       * @param mixed $value Value to assign
       * @return void
       */
      public function __set( $property, $value ) {
          if ( property_exists( $this, $property ) ) {
              $this->{$property} = $value;
          }
      }
  }
  
  $person = new Person();
  $person->set( 'name', 'John Doe' );
  • 6.5 Note: Magic getter and setter methods are slower than normal getter and setter methods. Also, there are problems with phpDoc.

⬆ back to top

Strings

  • 7.1 Use single quotes '' for strings.
  $person->name = 'John Doe';
  • 7.2 Strings, whose length exceeds the maximum amount of characters per line and would extend beyond the Right Margin (100 characters), should be split up and written across multiple lines using string concatenation.
  $person->description = 'I am a very long text and need to be written across multiple lines using string ' .
      'concatenation.';
  • 7.3 When programmatically building up strings, use sprintf instead of concatenation.
  $lastName = 'Doe';
  $person->name = sprintf( 'John %s', $lastName );

⬆ back to top

Functions

  • 8.1 Never declare a function in a non-function block (if, while, etc).
  // Don't do this!
  if ( $isTrue ) {
      function createPerson() {}
  }
  • 8.2 Use default parameter syntax rather than mutating function arguments.
  function createPerson( $name = '' ) {}

⬆ back to top

Comparison Operators & Equality

  • 9.1 Use === and !== over == and !=.

⬆ back to top

Blocks

  • 10.1 Use braces with all multi-line blocks.
  if ( !$person->age ) return false; 
  // or
  if ( !$person->age ) {
      return false;
  }
  
  // but NOT
  if ( !$person->age ) { return false; }
  // or
  if ( !$person->age )
      return false;
  • 10.2 If you're using multi-line blocks with if and else, put else on the same line as your if block's closing brace.
  if ( $person->cars ) {
      echo 'Nice cars!';
  } else {
      echo 'Riding bike?';
  }

⬆ back to top

Comments

  • 11.1 Use /** ... */ for multi-line comments. Include a description, specify types and values for all parameters and return values.
  /**
   * The class representing a person.
   *
   * Represents a person and all things one can do.
   *
   * @since 1.0
   * @package MarvelUniverse
   * @subpackage MarvelUniverse/Person
   * @author R4c00n <[email protected]>
   */
  class Person {
      public function __contruct() {}

      /**
       * Walks the line for a given amount of meters.
       *
       * @since 1.0
       * @param int $meters Meters to walk
       * @return void
       */
      public function walkTheLine( $meters ) {
          echo sprintf( 'I am walking the line for %dm.', $meters );
      }
  }
  • 11.2 Add phpDocs to your file.
  /**
   * Super hero functionality of the MarvelUniverse.
   *
   * @since 1.0
   * @package MarvelUniverse
   * @subpackage MarvelUniverse/SuperHero
   * @author R4c00n <[email protected]>
   */

  • 11.2 Note: For more information see phpDocumentor.

  • 11.3 Use # for single line comments. Place single line comments on a newline above the subject of the comment. Put an empty line before the comment.

  echo 'Look at dat comment';
  
  # Create a new person
  $person = new Person();
  • 11.4 Use # FIXME: to annotate problems.
  # FIXME: Something is wrong here, please fix it
  • 11.5 Use # TODO: to annotate solutions to problems.
  # TODO: Write more code!

⬆ back to top