[Summary view] [Print] [Text view]

   1  @title PHP Coding Standards
   2  @group standards
   3  
   4  This document describes PHP coding standards for Phabricator and related
   5  projects (like Arcanist and libphutil).
   6  
   7  = Overview =
   8  
   9  This document outlines technical and style guidelines which are followed in
  10  libphutil. Contributors should also follow these guidelines. Many of these
  11  guidelines are automatically enforced by lint.
  12  
  13  These guidelines are essentially identical to the Facebook guidelines, since I
  14  basically copy-pasted them. If you are already familiar with the Facebook
  15  guidelines, you probably don't need to read this super thoroughly.
  16  
  17  
  18  = Spaces, Linebreaks and Indentation =
  19  
  20    - Use two spaces for indentation. Don't use tab literal characters.
  21    - Use Unix linebreaks ("\n"), not MSDOS ("\r\n") or OS9 ("\r").
  22    - Use K&R style braces and spacing.
  23    - Put a space after control keywords like ##if## and ##for##.
  24    - Put a space after commas in argument lists.
  25    - Put a space around operators like ##=##, ##<##, etc.
  26    - Don't put spaces after function names.
  27    - Parentheses should hug their contents.
  28    - Generally, prefer to wrap code at 80 columns.
  29  
  30  = Case and Capitalization =
  31  
  32    - Name variables and functions using ##lowercase_with_underscores##.
  33    - Name classes using ##UpperCamelCase##.
  34    - Name methods and properties using ##lowerCamelCase##.
  35    - Use uppercase for common acronyms like ID and HTML.
  36    - Name constants using ##UPPERCASE##.
  37    - Write ##true##, ##false## and ##null## in lowercase.
  38  
  39  = Comments =
  40  
  41    - Do not use "#" (shell-style) comments.
  42    - Prefer "//" comments inside function and method bodies.
  43  
  44  = PHP Language Style =
  45  
  46    - Use "<?php", not the "<?" short form. Omit the closing "?>" tag.
  47    - Prefer casts like ##(string)## to casting functions like ##strval()##.
  48    - Prefer type checks like ##$v === null## to type functions like
  49      ##is_null()##.
  50    - Avoid all crazy alternate forms of language constructs like "endwhile"
  51      and "<>".
  52    - Always put braces around conditional and loop blocks.
  53  
  54  = PHP Language Features =
  55  
  56    - Use PHP as a programming language, not a templating language.
  57    - Avoid globals.
  58    - Avoid extract().
  59    - Avoid eval().
  60    - Avoid variable variables.
  61    - Prefer classes over functions.
  62    - Prefer class constants over defines.
  63    - Avoid naked class properties; instead, define accessors.
  64    - Use exceptions for error conditions.
  65    - Use type hints, use `assert_instances_of()` for arrays holding objects.
  66  
  67  = Examples =
  68  
  69  **if/else:**
  70  
  71    if ($some_variable > 3) {
  72      // ...
  73    } else if ($some_variable === null) {
  74      // ...
  75    } else {
  76      // ...
  77    }
  78  
  79  You should always put braces around the body of an if clause, even if it is only
  80  one line long. Note spaces around operators and after control statements. Do not
  81  use the "endif" construct, and write "else if" as two words.
  82  
  83  **for:**
  84  
  85    for ($ii = 0; $ii < 10; $ii++) {
  86      // ...
  87    }
  88  
  89  Prefer $ii, $jj, $kk, etc., as iterators, since they're easier to pick out
  90  visually and react better to "Find Next..." in editors.
  91  
  92  **foreach:**
  93  
  94    foreach ($map as $key => $value) {
  95      // ...
  96    }
  97  
  98  **switch:**
  99  
 100    switch ($value) {
 101      case 1:
 102        // ...
 103        break;
 104      case 2:
 105        if ($flag) {
 106          // ...
 107          break;
 108        }
 109        break;
 110      default:
 111        // ...
 112        break;
 113    }
 114  
 115  `break` statements should be indented to block level.
 116  
 117  **array literals:**
 118  
 119    $junk = array(
 120      'nuts',
 121      'bolts',
 122      'refuse',
 123    );
 124  
 125  Use a trailing comma and put the closing parenthesis on a separate line so that
 126  diffs which add elements to the array affect only one line.
 127  
 128  **operators:**
 129  
 130    $a + $b;                // Put spaces around operators.
 131    $omg.$lol;              // Exception: no spaces around string concatenation.
 132    $arr[] = $element;      // Couple [] with the array when appending.
 133    $obj = new Thing();     // Always use parens.
 134  
 135  **function/method calls:**
 136  
 137    // One line
 138    eject($cargo);
 139  
 140    // Multiline
 141    AbstractFireFactoryFactoryEngine::promulgateConflagrationInstance(
 142      $fuel,
 143      $ignition_source);
 144  
 145  **function/method definitions:**
 146  
 147    function example_function($base_value, $additional_value) {
 148      return $base_value + $additional_value;
 149    }
 150  
 151    class C {
 152      public static function promulgateConflagrationInstance(
 153        IFuel $fuel,
 154        IgnitionSource $source) {
 155        // ...
 156      }
 157    }
 158  
 159  **class:**
 160  
 161    class Dog extends Animal {
 162  
 163      const CIRCLES_REQUIRED_TO_LIE_DOWN = 3;
 164  
 165      private $favoriteFood = 'dirt';
 166  
 167      public function getFavoriteFood() {
 168        return $this->favoriteFood;
 169      }
 170    }