silverstripe-framework/docs/en/05_Contributing/14_PHP_Coding_Conventions.md

PHP Coding Conventions

This document provides guidelines for code formatting and documentation to developers contributing to SilverStripe. It applies to all PHP files in the framework/ and cms/ modules, as well as any supported additional modules.

Coding standards are an important aspect for every software project, and facilitate collaboration by making code more consistent and readable.

If you are unsure about a specific standard, imitate existing SilverStripe code.

PSR-2

Starting with SilverStripe 4.x, our goal is PSR-2 Coding Standards compliance. Since this affects existing APIs, some details like method casing will be iterated on in the next releases. For example, many static methods will need to be changed from lower underscore to lower camel casing.

Spelling

All symbols and documentation should use UK-English spelling (e.g. "behaviour" instead of "behavior"), except when necessitated by third party conventions (e.g using PHP's Serializable interface).

Configuration Variables

SilverStripe's Config API can read its defaults from variables declared as private static on classes. As opposed to other variables, these should be declared as lower case with underscores.

class MyClass
{
    private static $my_config_variable = 'foo';
}

Prefer identical (===) comparisons over equality (==)

Where possible, use type-strict identical comparisons instead of loosely typed equality comparisons. Read more in the PHP documentation for comparison operators and object comparison.

// good - only need to cast to (int) if $a might not already be an int
if ((int)$a === 100) {
    doThis();
}

// bad
if ($a == 100) {
    doThis();
}

Separation of Logic and Presentation

Try to avoid using PHP's ability to mix HTML into the code.

// PHP code
public function getTitle() 
{
    return "<h2>Bad Example</h2>";
}

// Template code
$Title

Better: Keep HTML in template files:

// PHP code
public function getTitle() 
{
    return "Better Example";
}

// Template code
<h2>$Title</h2>

Comments

Use phpdoc syntax before each definition (see tutorial and tag overview).

• Methods should include at least @param and @return.
• Include a blank line after the description.
• Use {@link MyOtherClass} and {@link MyOtherClass->otherMethod} for inline references.
• Denote preformatted code examples in <code></code> blocks.
• Always start block-level comments containing phpdoc with two asterisks (/** ... */).

Example:

/**
 * My short description for this class.
 * My longer description with
 * multiple lines and richer formatting.
 *
 * Usage:
 * <code>
 * $c = new MyClass();
 * $c->myMethod();
 * </code>
 *
 * @package custom
 */
class MyClass extends Class
{
    /**
     * My Method.
     * This method returns something cool. {@link MyParentMethod} has other cool stuff in it.
     *
     * @param string $colour The colour of cool things that you want
     * @return DataList A list of everything cool
     */
    public function myMethod($colour)
    {
        // ...
    }

}

Class Member Ordering

Put code into the classes in the following order (where applicable).

• Static variables
• Member variables
• Static methods
• Data-model definition static variables. ($db, $has_one, $many_many, etc)
• Commonly used methods like getCMSFields()
• Accessor methods (getMyField() and setMyField())
• Controller action methods
• Template data-access methods (methods that will be called by a $MethodName or <% loop $MethodName %> construct in a template somewhere)
• Object methods

SQL Format

If you have to use raw SQL, make sure your code works across databases. Make sure you escape your queries like below, with the column or table name escaped with double quotes as below.

MyClass::get()->where(['"Score" > ?' => 50]);

It is preferable to use parameterised queries whenever necessary to provide conditions to a SQL query, where values placeholders are each replaced with a single unquoted question mark. If it's absolutely necessary to use literal values in a query make sure that values are single quoted.

MyClass::get()->where("\"Title\" = 'my title'");

Use ANSI SQL format where possible.

Secure Development

See security for conventions related to handing security permissions.

Related

• JavaScript Coding Conventions
• Reference: CMS Architecture