Web Development/PHP Coding Standards

---

Revision as of 08:12, 16 June 2011

This document outlines technical and style guidelines which are followed in website-darenet. Contributors should also follow these guidelines.

In This Guide: 1 Spaces, Linebreaks and Identation 2 Case and Capitalization 3 Comments 4 PHP Language Style 5 PHP Language Features 6 Examples 6.1 if/else: 6.2 for: 6.3 foreach: 6.4 switch: 6.5 array literals: 6.6 operators: 6.7 function/method calls: 6.8 function/method definitions: 6.9 class:

Spaces, Linebreaks and Identation

• Use one tab for each level of indentation.
• Use Unix linebreaks ("\n"), not MSDOS ("\r\n") or OS9 ("\r").
• Use K&R style braces and spacing.
• Put a space after control keywords like if and for.
• Put a space after commas in argument lists.
• Put a space around operators like =, <, etc.
• Don't put spaces after function names.
• Parentheses should hug their contents.
• Generally, prefer to wrap code at 80 columns.

Case and Capitalization

• Name variables and functions using lowercase_with_underscores.
• Name classes using UpperCamelCase.
• Name methods and properties using lowerCamelCase.
• Use uppercase for common acronyms like ID and HTML.
• Name constants using UPPERCASE.
• Write true, false and null in lowercase.

Comments

• Do not use "#" (shell-style) comments.
• Prefer "//" comments inside function and method bodies.

PHP Language Style

• Use "<?php", not the "<?" short form. Omit the closing "?>" tag.
• Prefer casts like (string) to casting functions like strval().
• Prefer type checks like $v === null to type functions like is_null().
• Avoid all crazy alternate forms of language constructs like "endwhile" and "<>" (acceptable in templates).
• Always put braces around conditional and loop blocks.

PHP Language Features

• Use PHP as a programming language, not a templating language.
• Avoid globals.
• Avoid extract().
• Avoid eval().
• Avoid variable variables.
• Prefer classes over functions.
• Prefer class constants over defines.
• Avoid naked class properties; instead, define accessors.
• Use exceptions for error conditions.

Examples

if/else:

if ($some_variable > 3) {
  // ...
} else if ($some_variable === null) {
  // ...
} else {
  // ...
}

You should always put braces around the body of an if clause, even if it is only one line long. Note spaces around operators and after control statements. Do not use the "endif" construct, and write "else if" as two words.

for:

for ($ii = 0; $ii < 10; $ii++) {
  // ...
}

Prefer $ii, $jj, $kk, etc., as iterators, since they're easier to pick out visually and react better to "Find Next..." in editors.

foreach:

foreach ($map as $key => $value) {
  // ...
}

switch:

switch ($value) {
  case 1:
    // ...
    break;
  case 2:
    if ($flag) {
      // ...
      break;
    }
    break;
  default:
    // ...
    break;
}

break statements should be indented to block level.

array literals:

$junk = array(
  'nuts',
  'bolts',
  'refuse',
);

Use a trailing comma and put the closing parenthesis on a separate line so that diffs which add elements to the array affect only one line.

operators:

$a + $b;                // Put spaces around operators.
$omg.$lol;              // Exception: no spaces around string concatenation.
$arr[] = $element;      // Couple [] with the array when appending.
$obj = new Thing();     // Always use parens.

function/method calls:

// One line
eject($cargo);
 
// Multiline
AbstractFireFactoryFactoryEngine::promulgateConflagrationInstance(
  $fuel,
  $ignition_source);

function/method definitions:

function example_function($base_value, $additional_value) {
  return $base_value + $additional_value;
}
 
class C {
  public static function promulgateConflagrationInstance(
    IFuel $fuel,
    IgnitionSource $source) {
    // ...
  }
}

class:

class Dog extends Animal {
 
  const CIRCLES_REQUIRED_TO_LIE_DOWN = 3;
 
  private $favoriteFood = 'dirt';
 
  public function getFavoriteFood() {
    return $this->favoriteFood;
  }
}