mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-09-19 16:06:32 +02:00
175 lines
5.2 KiB
Markdown
175 lines
5.2 KiB
Markdown
# 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](http://www.php-fig.org/psr/psr-2/) 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.
|
|
|
|
|
|
```php
|
|
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](http://php.net/manual/en/language.operators.comparison.php) and [object comparison](http://php.net/manual/en/language.oop5.object-comparison.php).
|
|
|
|
|
|
```php
|
|
// 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
|
|
// PHP code
|
|
public function getTitle()
|
|
{
|
|
return "<h2>Bad Example</h2>";
|
|
}
|
|
|
|
// Template code
|
|
$Title
|
|
```
|
|
|
|
Better: Keep HTML in template files:
|
|
|
|
|
|
```php
|
|
// PHP code
|
|
public function getTitle()
|
|
{
|
|
return "Better Example";
|
|
}
|
|
|
|
// Template code
|
|
<h2>$Title</h2>
|
|
```
|
|
|
|
## Comments
|
|
|
|
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 DataList A list of everything cool
|
|
*/
|
|
public function myMethod($foo)
|
|
{
|
|
// ...
|
|
}
|
|
|
|
}
|
|
```
|
|
|
|
## 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.
|
|
|
|
|
|
```php
|
|
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.
|
|
|
|
|
|
```php
|
|
MyClass::get()->where("\"Title\" = 'my title'");
|
|
```
|
|
|
|
Use [ANSI SQL](http://en.wikipedia.org/wiki/SQL#Standardization) format where possible.
|
|
|
|
## Secure Development
|
|
|
|
See [security](/developer_guides/security) for conventions related to handing security permissions.
|
|
|
|
## Related
|
|
|
|
* [JavaScript Coding Conventions](/contributing/javascript_coding_conventions)
|
|
* [Reference: CMS Architecture](/developer_guides/customising_the_admin_interface/cms_architecture)
|