Coding Standards

Coding Standards

CakePHP developers will use the PSR-2 coding style guide in addition to the following rules ascoding standards.

It is recommended that others developing CakeIngredients follow the samestandards.

You can use the CakePHP Code Sniffer to check that your codefollows required standards.

Adding New Features

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

IDE Setup

Please make sure your IDE is set up to “trim right” on whitespaces.There should be no trailing spaces per line.

Most modern IDEs also support an .editorconfig file. The CakePHP appskeleton ships with it by default. It already contains best practise defaults.

We recommend to use the IdeHelper plugin if youwant to maximize IDE compatibility. It will assist to keep the annotations up-to-date which will makethe IDE fully understand how all classes work together and provides better type-hinting and auto-completion.

Indentation

Four spaces will be used for indentation.

So, indentation should look like this:

// base level
    // level 1
        // level 2
    // level 1
// base level

Or:

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

In cases where you’re using a multi-line function call use the followingguidelines:

Opening parenthesis of a multi-line function call must be the last content onthe line.
Only one argument is allowed per line in a multi-line function call.
Closing parenthesis of a multi-line function call must be on a line by itself.
As an example, instead of using the following formatting:

$matches = array_intersect_key($this->_listeners,
                array_flip(preg_grep($matchPattern,
                    array_keys($this->_listeners), 0)));

Use this instead:

$matches = array_intersect_key(
    $this->_listeners,
    array_flip(
        preg_grep($matchPattern, array_keys($this->_listeners), 0)
    )
);

Line Length

It is recommended to keep lines at approximately 100 characters long for bettercode readability. A limit of 80 or 120 characters makes it necessary todistribute complex logic or expressions by function, as well as give functionsand objects shorter, more expressive names. Lines must not belonger than 120 characters.

In short:

100 characters is the soft limit.
120 characters is the hard limit.

Control Structures

Control structures are for example “if”, “for”, “foreach”,“while”, “switch” etc. Below, an example with “if”:

if ((expr_1) || (expr_2)) {
    // action_1;
} elseif (!(expr_3) && (expr_4)) {
    // action_2;
} else {
    // default_action;
}

In the control structures there should be 1 (one) space before the firstparenthesis and 1 (one) space between the last parenthesis and the openingbracket.
Always use curly brackets in control structures, even if they are not needed.They increase the readability of the code, and they give you fewer logicalerrors.
Opening curly brackets should be placed on the same line as the controlstructure. Closing curly brackets should be placed on new lines, and theyshould have same indentation level as the control structure. The statementincluded in curly brackets should begin on a new line, and code containedwithin it should gain a new level of indentation.
Inline assignments should not be used inside of the control structures.

// wrong = no brackets, badly placed statement
if (expr) statement;
 
// wrong = no brackets
if (expr)
    statement;
 
// good
if (expr) {
    statement;
}
 
// wrong = inline assignment
if ($variable = Class::function()) {
    statement;
}
 
// good
$variable = Class::function();
if ($variable) {
    statement;
}

Ternary Operator

Ternary operators are permissible when the entire ternary operation fits on oneline. Longer ternaries should be split into if else statements. Ternaryoperators should not ever be nested. Optionally parentheses can be used aroundthe condition check of the ternary for clarity:

// Good, simple and readable
$variable = isset($options['variable']) ? $options['variable'] : true;
 
// Nested ternaries are bad
$variable = isset($options['variable']) ? isset($options['othervar']) ? true : false : false;

Template Files

In template files (.ctp files) developers should use keyword control structures.Keyword control structures are easier to read in complex template files. Controlstructures can either be contained in a larger PHP block, or in separate PHPtags:

<?php
if ($isAdmin):
    echo '<p>You are the admin user.</p>';
endif;
?>
<p>The following is also acceptable:</p>
<?php if ($isAdmin): ?>
    <p>You are the admin user.</p>
<?php endif; ?>

Comparison

Always try to be as strict as possible. If a non-strict test is deliberate itmight be wise to comment it as such to avoid confusing it for a mistake.

For testing if a variable is null, it is recommended to use a strict check:

if ($value === null) {
    // ...
}

The value to check against should be placed on the right side:

// not recommended
if (null === $this->foo()) {
    // ...
}
 
// recommended
if ($this->foo() === null) {
    // ...
}

Function Calls

Functions should be called without space between function’s name and startingparenthesis. There should be one space between every parameter of a functioncall:

$var = foo($bar, $bar2, $bar3);

As you can see above there should be one space on both sides of equals sign (=).

Method Definition

Example of a method definition:

public function someFunction($arg1, $arg2 = '')
{
    if (expr) {
        statement;
    }
 
    return $var;
}

Parameters with a default value, should be placed last in function definition.Try to make your functions return something, at least true or false, soit can be determined whether the function call was successful:

public function connection($dns, $persistent = false)
{
    if (is_array($dns)) {
        $dnsInfo = $dns;
    } else {
        $dnsInfo = BD::parseDNS($dns);
    }
 
    if (!($dnsInfo) || !($dnsInfo['phpType'])) {
        return $this->addError();
    }
 
    return true;
}

There are spaces on both side of the equals sign.

Bail Early

Try to avoid unnecessary nesting by bailing early:

public function run(array $data)
{
    ...
    if (!$success) {
        return false;
    }
 
    ...
}
 
public function check(array $data)
{
    ...
    if (!$success) {
        throw new RuntimeException(...);
    }
 
    ...
}

This helps to keep the code flow simple and easy to follow.

Typehinting

Arguments that expect objects, arrays or callbacks (callable) can be typehinted.We only typehint public methods, though, as typehinting is not cost-free:

/**
 * Some method description.
 *
 * @param \Cake\ORM\Table $table The table class to use.
 * @param array $array Some array value.
 * @param callable $callback Some callback.
 * @param bool $boolean Some boolean value.
 */
public function foo(Table $table, array $array, callable $callback, $boolean)
{
}

Here $table must be an instance of \Cake\ORM\Table, $array must bean array and $callback must be of type callable (a valid callback).

Note that if you want to allow $array to be also an instance of\ArrayObject you should not typehint as array accepts only the primitivetype:

/**
 * Some method description.
 *
 * @param array|\ArrayObject $array Some array value.
 */
public function foo($array)
{
}

Anonymous Functions (Closures)

Defining anonymous functions follows the PSR-2 coding style guide, where they aredeclared with a space after the function keyword, and a space before and afterthe use keyword:

$closure = function ($arg1, $arg2) use ($var1, $var2) {
    // code
};

Method Chaining

Method chaining should have multiple methods spread across separate lines, andindented with four spaces:

$email->from('foo@example.com')
    ->to('bar@example.com')
    ->subject('A great message')
    ->send();

Commenting Code

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

Comments can include the following phpDocumentortags:

@author
@copyright
@deprecatedUsing the @version <vector> <description> format, where versionand description are mandatory. Version refers to the one it got deprecated in.
@example
@ignore
@internal
@link
@see
@since
@version
PhpDoc tags are very much like JavaDoc tags in Java. Tags are only processed ifthey are the first thing in a DocBlock line, for example:

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

/**
 * Example of inline phpDoc tags.
 *
 * This function works hard with foo() to rule the world.
 *
 * @return void
 */
function bar()
{
}
 
/**
 * Foo function.
 *
 * @return void
 */
function foo()
{
}

Comment blocks, with the exception of the first block in a file, should alwaysbe preceded by a newline.

Variable Types

Variable types for use in DocBlocks:

Type
Description
mixed
A variable with undefined (or multiple) type.
int
Integer type variable (whole number).
float
Float type (point number).
bool
Logical type (true or false).
string
String type (any value in ” ” or ‘ ‘).
null
Null type. Usually used in conjunction with another type.
array
Array type.
object
Object type. A specific class name should be used if possible.
resource
Resource type (returned by for example mysql_connect()).Remember that when you specify the type as mixed, you should indicatewhether it is unknown, or what the possible types are.
callable
Callable function.
You can also combine types using the pipe char:

int|bool

For more than two types it is usually best to just use mixed.

When returning the object itself, e.g. for chaining, one should use $thisinstead:

/**
 * Foo function.
 *
 * @return $this
 */
public function foo()
{
    return $this;
}

Including Files

include, require, include_once and require_once do not haveparentheses:

// wrong = parentheses
require_once('ClassFileName.php');
require_once ($class);
 
// good = no parentheses
require_once 'ClassFileName.php';
require_once $class;

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

PHP Tags

Always use long tags (<?php ?>) instead of short tags (<? ?>). The shortecho should be used in template files (.ctp) where appropriate.

Short Echo

The short echo should be used in template files in place of <?php echo. Itshould be immediately followed by a single space, the variable or function valueto echo, a single space, and the php closing tag:

// wrong = semicolon, no spaces
<td><?=$name;?></td>
 
// good = spaces, no semicolon
<td><?= $name ?></td>

As of PHP 5.4 the short echo tag (<?=) is no longer to be consider a ‘shorttag’ is always available regardless of the short_open_tag ini directive.

Naming Convention

Functions

Write all functions in camelBack:

function longFunctionName()
{
}

Classes

Class names should be written in CamelCase, for example:

class ExampleClass
{
}

Variables

Variable names should be as descriptive as possible, but also as short aspossible. All variables should start with a lowercase letter, and should bewritten in camelBack in case of multiple words. Variables referencing objectsshould in some way associate to the class the variable is an object of.Example:

$user = 'John';
$users = ['John', 'Hans', 'Arne'];
 
$dispatcher = new Dispatcher();

Member Visibility

Use PHP’s public, protected and private keywords for methods and variables.

Example Addresses

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
The “example.com” domain name has been reserved for this (see RFC 2606) andis recommended for use in documentation or as examples.

Files

File names which do not contain classes should be lowercased and underscored,for example:

long_file_name.php

Casting

For casting we use:

Type
Description
(bool)
Cast to boolean.
(int)
Cast to integer.
(float)
Cast to float.
(string)
Cast to string.
(array)
Cast to array.
(object)
Cast to object.
Please use (int)$var instead of intval($var) and (float)$var insteadof floatval($var) when applicable.

Constants

Constants should be defined in capital letters:

define('CONSTANT', 1);

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

define('LONG_NAMED_CONSTANT', 2);

Careful when using empty()/isset()

While empty() is an easy to use function, it can mask errors and causeunintended effects when '0' and 0 are given. When variables orproperties are already defined, the usage of empty() is not recommended.When working with variables, it is better to rely on type-coercion to booleaninstead of empty():

function manipulate($var)
{
    // Not recommended, $var is already defined in the scope
    if (empty($var)) {
        // ...
    }
 
    // Use boolean type coercion
    if (!$var) {
        // ...
    }
    if ($var) {
        // ...
    }
}

When dealing with defined properties you should favour null checks overempty()/isset() checks:

class Thing
{
    private $property; // Defined
 
    public function readProperty()
    {
        // Not recommended as the property is defined in the class
        if (!isset($this->property)) {
            // ...
        }
        // Recommended
        if ($this->property === null) {
 
        }
    }
}

When working with arrays, it is better to merge in defaults over usingempty() checks. By merging in defaults, you can ensure that required keysare defined:

function doWork(array $array)
{
    // Merge defaults to remove need for empty checks.
    $array += [
        'key' => null,
    ];
 
    // Not recommended, the key is already set
    if (isset($array['key'])) {
        // ...
    }
 
    // Recommended
    if ($array['key'] !== null) {
        // ...
    }
}