Welcome to The Cookbook

No new features should be added, without having their own tests - which should be passed before committing them to the repository.

One tab will be used for indentation.

So, indentation should look like this:

<?php
// base level
    // level 1
        // level 2
    // level 1
// base level
?>

1. <?php
2. // base level
3. // level 1
4. // level 2
5. // level 1
6. // base level
7. ?>

Or:

$booleanVariable = true;
$stringVariable = "moose";
if ($booleanVariable) {
    echo "Boolean value is true";
    if ($stringVariable = "moose") {
        echo "We have encountered a moose";
    }
}

1. $booleanVariable = true;
2. $stringVariable = "moose";
3. if ($booleanVariable) {
4. echo "Boolean value is true";
5. if ($stringVariable = "moose") {
6. echo "We have encountered a moose";
7. }
8. }

Functions should be called without space between function's name and starting bracket. There should be one space between every parameter of a function call.

<?php 
$var = foo($bar, $bar2, $bar3); 
?>

1. <?php
2. $var = foo($bar, $bar2, $bar3);
3. ?>

As you can see above there should be one space on both sides of equals sign (=). To increase the readability of the code you can add spaces (or tabs) before the equals sign, but only in the case of a multiple function call presented below:

<?php 
$varShort     = foo($bar1);
$variableLong = foo($bar1);
?>

1. <?php
2. $varShort = foo($bar1);
3. $variableLong = foo($bar1);
4. ?>

All comments should be written in English, and should in a clear way describe the commented block of code.

Comments can include the following phpDocumentor tags:

• @access
• @author
• @copyright
• @deprecated
• @example
• @ignore
• @internal
• @link
• @see
• @since
• @tutorial
• @version
• inline {@internal}}
• inline {@inheritdoc}}
• inline {@link}}

PhpDoc tags are very much like JavaDoc tags in Java. Tags are only processed if they are the first thing in a DocBlock line, for example:

<?php
/**
 * Tag example.
 * @author this tag is parsed, but this @version is ignored
 * @version 1.0 this tag is also parsed
 */
?>

1. <?php
2. /**
3. * Tag example.
4. * @author this tag is parsed, but this @version is ignored
5. * @version 1.0 this tag is also parsed
6. */
7. ?>

There are 3 inline tags ({@internal}}, {@inheritdoc}} and {@link}}).

<?php
/**
 * Example of inline phpDoc tags.
 *
 * This function works hard with {@link foo()} to rule the world.
 */
function bar() {
}

function foo() {
}
?>

1. <?php
2. /**
3. * Example of inline phpDoc tags.
4. *
5. * This function works hard with {@link foo()} to rule the world.
6. */
7. function bar() {
8. }
9. function foo() {
10. }
11. ?>

When including files with classes or libraries, use only and always the require_once function.

Always use long tags (<?php ?>) Instead of short tags (<? ?>).

Write all functions in camel case

<?php
function longFunctionName() {
}
?>

1. <?php
2. function longFunctionName() {
3. }
4. ?>

Class names should be written in CamelCase, for example:

<?php
class ExampleClass {
}
?>

1. <?php
2. class ExampleClass {
3. }
4. ?>

Variable names should be as descriptive as possible, but also as short as possible. Normal variables should start with a lowercase letter, and should be written in camelBack? in case of multiple words. Variables containing objects should start with a capital letter, and in some way associate to the class the variable is an object of. Example:

<?php
$user = 'John';
$users = array('John', 'Hans', 'Arne');

$Dispatcher = new Dispatcher();
?>

1. <?php
2. $user = 'John';
3. $users = array('John', 'Hans', 'Arne');
4. $Dispatcher = new Dispatcher();
5. ?>

As we cannot use PHP5's private and protected keywords for methods or variables, we agree on following rules:

• A protected method or variable name start with a single underscore ("_"). Example:

  <?php
  class A {
      var _iAmAProtectedVariable;
  
      function _iAmAProtectedMethod() {
          /*...*/
      }
  }
  ?>
  

  1. <?php
  2. class A {
  3. var _iAmAProtectedVariable;
  4. function _iAmAProtectedMethod() {
  5. /*...*/
  6. }
  7. }
  8. ?>
• A private method or variable name start with double underscore ("__"). Example:

<?php
class A {
    var __iAmAPrivateVariable;

    function __iAmAPrivateMethod() {
        /*...*/
    }
}
?>

1. <?php
2. class A {
3. var __iAmAPrivateVariable;
4. function __iAmAPrivateMethod() {
5. /*...*/
6. }
7. }
8. ?>

For all example URL and mail addresses use "example.com", "example.org" and "example.net", for example:

• Email: someone@example.com
• WWW: http://www.example.com
• FTP: ftp://ftp.example.com

File names should be created with lower case. If a file name consist of multiple words, they should be divided by an underscore character, for example:

long_file_name.php

Variable types for use in DocBlocks:

Remember that when you specify the type as mixed, you should indicate whether it is unknown, or what the possible types are.

Constants should be defined in capital letters:

<?php
define('CONSTANT', 1);
?>

1. <?php
2. define('CONSTANT', 1);
3. ?>

If a constant name consists of multiple words, they should be separated by an underscore character, for example:

<?php
define('LONG_NAMED_CONSTANT', 2);
?>

1. <?php
2. define('LONG_NAMED_CONSTANT', 2);
3. ?>