The following code style is used for Yii 2.x core and official extensions development. If you want to pull-request code into the core, consider using it. We aren't forcing you to use this code style for your application. Feel free to choose what suits you better.
You can get a config for CodeSniffer here: https://github.com/yiisoft/yii2-coding-standards
1. Overview
-----------
- Files MUST use either `<?php` or `<?=` tags.
- There should be a newline at the end of file.
- Files MUST use only UTF-8 without BOM for PHP code.
- Code MUST use tabs for indenting, not spaces.
- Class names MUST be declared in `StudlyCaps`.
- Class constants MUST be declared in all upper case with underscore separators.
- Method names MUST be declared in `camelCase`.
- Property names MUST be declared in `camelCase`.
- Property names MUST start with an initial underscore if they are private.
- Always use `elseif` instead of `else if`.
2. Files
--------
### 2.1. PHP Tags
- PHP code MUST use `<?php ?>` or `<?=` tags; it MUST NOT use the other tag variations such as `<?`.
- In case file contains PHP only it should not have trailing `?>`.
- Do not add trailing spaces to the end of the lines.
- Any file that contains PHP code should end with the extension `.php`.
### 2.2. Character Encoding
PHP code MUST use only UTF-8 without BOM.
3. Class Names
--------------
Class names MUST be declared in `StudlyCaps`. For example, `Controller`, `Model`.
4. Classes
----------
The term "class" refers to all classes and interfaces here.
- Classes should be named using `CamelCase`.
- The brace should always be written on the line underneath the class name.
- Every class must have a documentation block that conforms to the PHPDoc.
- All code in a class must be indented with a single tab.
- There should be only one class in a single PHP file.
- All classes should be namespaced.
- Class name should match file name. Class namespace should match directory structure.
Class constants MUST be declared in all upper case with underscore separators.
For example:
```php
<?php
classFoo
{
constVERSION='1.0';
constDATE_APPROVED='2012-06-01';
}
```
### 4.2. Properties
- When declaring public class members specify `public` keyword explicitly.
- Variables should be declared at the top of the class before any method declarations.
- Private variables should be named like `$_varName`.
- Public class members and standalone variables should be named using `$camelCase`
with first letter lowercase.
- Use descriptive names. Variables such as `$i` and `$j` are better not to be used.
For example:
```php
<?php
classFoo
{
public$publicProp;
protected$protectedProp;
private$_privateProp;
}
```
### 4.3. Methods
- Functions and methods should be named using `camelCase` with first letter lowercase.
- Name should be descriptive by itself indicating the purpose of the function.
- Class methods should always declare visibility using `private`, `protected` and
`public` modifiers. `var` is not allowed.
- Opening brace of a function should be on the line after the function declaration.
~~~
/**
* Documentation
*/
class Foo
{
/**
* Documentation
*/
public function bar()
{
// code
return $value;
}
}
~~~
### 4.4 Doc blocks
`@param`, `@var`, `@property` and `@return` must declare types as `boolean`, `integer`, `string`, `array` or `null`. You can use a class names as well such as `Model` or `ActiveRecord`. For a typed arrays use `ClassName[]`.
### 4.5 Constructors
-`__construct` should be used instead of PHP 4 style constructors.
- When instantiating class it should be `new MyClass();` instead of `new MyClass;`.
## 5 PHP
### 5.1 Types
- All PHP types and values should be used lowercase. That includes `true`, `false`, `null` and `array`.
Use the following format for associative arrays:
```php
$config=[
'name'=>'Yii',
'options'=>['usePHP'=>true],
];
```
Changing type of an existing variable is considered as a bad practice. Try not to write such code unless it is really necessary.
```php
public function save(Transaction $transaction, $argument2 = 100)
{
$transaction = new Connection; // bad
$argument2 = 200; // good
}
```
### 5.2 Strings
- If string doesn't contain variables or single quotes, use single quotes.
```php
$str='Like this.';
```
- If string contains single quotes you can use double quotes to avoid extra escaping.
#### Variable substitution
```php
$str1="Hello $username!";
$str2="Hello {$username}!";
```
The following is not permitted:
```php
$str3="Hello ${username}!";
```
#### Concatenation
Add spaces around dot when concatenating strings:
```php
$name='Yii'.' Framework';
```
When string is long format is the following:
```php
$sql="SELECT *"
."FROM `post` "
."WHERE `id` = 121 ";
```
### 5.3 arrays
For arrays we're using PHP 5.3 short array syntax.
#### Numerically indexed
- Do not use negative numbers as array indexes.
Use the following formatting when declaring array:
```php
$arr=[3,14,15,'Yii','Framework'];
```
If there are too many elements for a single line:
```php
$arr=[
3,14,15,
92,6,$test,
'Yii','Framework',
];
```
#### Associative
Use the following format for associative arrays:
```php
$config=[
'name'=>'Yii',
'options'=>['usePHP'=>true],
];
```
### 5.4 control statements
- Control statement condition must have single space before and after parenthesis.
- Operators inside of parenthesis should be separated by spaces.
- Opening brace is on the same line.
- Closing brace is on a new line.
- Always use braces for single line statements.
```php
if($event===null){
returnnewEvent();
}elseif($eventinstanceofCoolEvent){
return$event->instance();
}else{
returnnull;
}
// the following is NOT allowed:
if(!$model&&null===$event)
thrownewException('test');
```
#### switch
Use the following formatting for switch:
```php
switch($this->phpType){
case'string':
$a=(string)$value;
break;
case'integer':
case'int':
$a=(integer)$value;
break;
case'boolean':
$a=(boolean)$value;
break;
default:
$a=null;
}
```
### 5.5 function calls
```php
doIt(2,3);
doIt(['a'=>'b']);
doIt('a',[
'a'=>'b',
'c'=>'d',
]);
```
### 5.6 Anonymous functions (lambda) declarations
Note space between `function`/`use` tokens and open parenthesis:
The following code style is used for Yii 2.x core and official extensions view files. We aren't forcing you to use this code style for your application. Feel free to choose what suits you better.
```php
<?php
// Leading PHP tag is a must in every template file. Empty line after leading PHP tag is also required.
// Describe input variables passed by controller here.
/**
* @var yii\base\View $this
* @var yii\widgets\ActiveForm $form
* @var app\models\Post[] $posts
* @var app\models\ContactMessage $contactMessage
*/
// Empty line below is necessary.
// Namespaced classes declaration.
useyii\helpers\Html;
useyii\widgets\ActiveForm;
// Empty line below is necessary.
// Set context properties, call its setters, do other things.
$this->title='Posts';
?>
<!-- Separate PHP blocks are preferred for foreach, for, if etc. -->
