All letters used in a constant name must be capitalized,
while all words in a constant name must be separated by underscore characters.
:::php
define('INTEREST_RATE', 0.19);
Constants must be defined as class members with the `const` modifier.
Defining constants in the global scope with the `define` function is permitted but strongly discouraged.
### File Naming and Directory Structure
Classes need to be in a file of the same name. Multiple classes are allowed to be contained in one file,
as long as the prefix of the class equals the filename, and is separated by an underscore from the remaining name.
For example `MyClass` and `MyClass_Controller` will both need to be placed into `MyClass.php`.
Example: `mysite/code/MyClass.php`
:::php
<?php
class MyClass {}
class MyClass_Controller {}
class MyClass_OtherRelatedClass {}
To help with namespacing common class names (like Database) it is recommended to use a prefix convention `SS_ClassName` but the filename will remain `ClassName.php`.
See [directory-structure](/topics/directory-structure) for more information.
## Coding Style
### PHP Code Declaration
PHP code must always be delimited by the full-form, standard PHP tags:
:::php
<?php
Short tags are never allowed. For files containing only PHP code, the closing tag must always be omitted.
It is not required by PHP, and omitting it prevents the accidental injection of trailing white space into the response.
### Strings
#### String Literals
When a string is literal (contains no variable substitutions), the apostrophe or "single quote" should always be used to demarcate the string:
:::php
$a = 'Example String';
#### String Literals Containing Apostrophes
When a literal string itself contains apostrophes, it is permitted to demarcate the string with quotation marks or "double quotes".
:::php
$greeting = "She said 'hello'";
This syntax is preferred over escaping apostrophes as it is much easier to read.
#### String Substitution
Variable substitution is permitted using either of these forms:
:::php
$greeting = "Hello $name, welcome back!";
$greeting = "Hello {$name}, welcome back!";
For consistency, placing the dollar sign outside of the brackets is not permitted:
:::php
$greeting = "Hello ${name}, welcome back!";
#### String Concatentation
Strings must be concatenated using the "." operator. A space must always be added before and after the "." operator to improve readability:
:::php
$copyright = 'SilverStripe Ltd (' . $year . ')';
When concatenating strings with the "." operator, it is encouraged to break the statement into multiple lines to improve readability.
In these cases, each successive line should be padded with white space such that the "."; operator is aligned under the "=" operator:
:::php
$sql = 'SELECT "ID", "Name" FROM "Person" '
. 'WHERE "Name" = \'Susan\' '
. 'ORDER BY "Name" ASC ';
### Arrays
#### Numerically Indexed Arrays
Negative numbers are not permitted as indices.
An indexed array may start with any non-negative number, however all base indices besides 0 are discouraged.
When declaring indexed arrays with the Array function, a trailing space must be added after each comma delimiter to improve readability:
:::php
$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
It is permitted to declare multi-line indexed arrays using the "array" construct.
In this case, each successive line must be padded with spaces such that beginning of each line is aligned:
:::php
$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
$a, $b, $c,
56.44, $d, 500);
Alternately, the initial array item may begin on the following line.
If so, it should be padded at one indentation level greater than the line containing the array declaration,
and all successive lines should have the same indentation;
the closing paren should be on a line by itself at the same indentation level as the line containing the array declaration:
:::php
$sampleArray = array(
1, 2, 3, 'Zend', 'Studio',
$a, $b, $c,
56.44, $d, 500,
);
When using this latter declaration, we encourage using a trailing comma for the last item in the array;
this minimizes the impact of adding new items on successive lines, and helps to ensure no parse errors occur due to a missing comma.
#### Associative Arrays
When declaring associative arrays with the `array` construct, breaking the statement into multiple lines is encouraged.
In this case, each successive line must be padded with white space such that both the keys and the values are aligned:
:::php
$sampleArray = array('firstKey' => 'firstValue',
'secondKey' => 'secondValue');
Alternately, the initial array item may begin on the following line.
If so, it should be padded at one indentation level greater than the line containing the array declaration,
and all successive lines should have the same indentation; the closing paren should be on a line by itself at the
same indentation level as the line containing the array declaration.
For readability, the various "=>" assignment operators should be padded such that they align.
:::php
$sampleArray = array(
'firstKey' => 'firstValue',
'secondKey' => 'secondValue',
);
### Function and Method Declaration
No method or function invocation is allowed to have spaces directly
before or after the opening parathesis, as well as no space before the closing parenthesis.
Use [phpdoc](http://phpdoc.org/) syntax before each definition (see [tutorial](http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.quickstart.pkg.html)
and [tag overview](http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html)).
* All class definitions and PHP files should have `@package` and `@subpackage`.
* 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:
:::php
/**
* 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 DataObjectSet A list of everything cool
*/
public function myMethod($foo) {}
}
### Class Member Ordering
Put code into the classes in the following order (where applicable).
