mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 14:05:37 +02:00

Andrew Aitken-Fincham 1e87528fa8

2020-11-10 11:35:13 +13:00

6.1 KiB

Raw Blame History

title	summary	iconBrand
PHP coding conventions	The code style guidelines we use in our open source software	php

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

Method/property visibility guidelines

When adding new methods and properties, should you make them public, protected, or private?

Public: Use this for public APIs. You should add tests and documentation for these.
Protected: Use for extensibility APIs. Note that compatibility for such APIs should be maintained in minor releases, and so you'll probably want to cover them in tests (i.e. test that these methods can be called from within a subclass and/or overridden). If that seems like overkill, consider whether it's safer to leave these as private for now.
Private: Use for class internals

Above all, recognise that when you are making something public or protected, you are creating an API for other developers to use and rely on, and do so with care. Don't simply dump class internals in as protected members in the name of extensibility – doing so will be likely to break developers' projects in minor releases.

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.

6.1 KiB Raw Blame History Unescape Escape