Стиль кодирования Yii 2 framework
=================================
Описанный ниже стиль кодирования используется при разработке ядра Yii 2.x и его официальных расширений. Если вы хотите участвовать в разработке фреймворка, постарайтесь придерживаться данного стиля. Мы не принуждаем вас использовать этот стиль при разработке ваших приложений с использованием Yii 2. В данном случае можете использовать тот стиль, который вам больше подходит.
Пример конфигурационного файла для CodeSniffer вы можете найти здесь: https://github.com/yiisoft/yii2-coding-standards
## 1. Обзор
В общем, мы используем совместимый со стандартом [PSR-2 ](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md ) стиль, так что все положения [PSR-2 ](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md ) вполне применимы к нашему стилю кодирования.
- ДОЛЖНЫ использоваться только открывающие теги `<?php` или `<?=` ;
- В конце файла должна быть пустая строка;
- Файлы с PHP кодом ДОЛЖНЫ содержать только символы в кодировке UTF-8 без BOM;
- Для выравнивания кода НУЖНО использовать 4 пробела вместо табуляции;
- Имена классов ДОЛЖНЫ быть объявлены используя `StudlyCaps` ;
- Константы класса ДОЛЖНЫ быть объявлены в верхнем регистре с подчеркиванием в качестве разделителей;
- Имена методов ДОЛЖНЫ быть объявлены используя `camelCase` ;
- Имена свойств ДОЛЖНЫ быть объявлены используя `camelCase` ;
- Имена свойств ДОЛЖНЫ начинаться с подчеркивания если они объявлены с использованием модификатора `private` ;
- Всегда используйте `elseif` вместо `else if` .
## 2. Файлы
### 2.1. Теги PHP
- В PHP коде ДОЛЖНЫ использоваться теги `<?php ?>` или `<?=` ; НЕ ДОЛЖНЫ использоваться другие теги, такие как `<?` ;
- Если файл содержит только PHP код, тогда закрывающий тег `?>` не нужен;
- Не добавляйте лишние пробелы в конец строки;
- Все файлы, содержащие PHP код, должны иметь расширение `.php` .
### 2.2. Кодировка символов
PHP код должен содержать только символы в кодировке UTF-8 без BOM.
## 3. Имена Классов
Имена классов ДОЛЖНЫ быть определены используя `StudlyCaps` . Например, `Controller` , `Model` .
## 4. Классы
В данном случае, под классом подразумеваются все классы и интерфейсы.
- При именовании классов следует использовать `CamelCase` ;
- Открывающая фигурная скобка всегда должна быть на следующей строке после имена класса;
- Все классы должны быть документированы в соответствии с PHPDoc;
- Весь код класса должен быть выровнен с использованием 4 пробелов;
- В одном PHP файле должен быть только один класс;
- Все классы должны использовать пространства имен;
- Имя класса должно совпадать с именем файла. Пространство имен класса должно соответствовать структуре каталогов.
```php
/**
* Документация
*/
class MyClass extends \yii\base\BaseObject implements MyInterface
{
// код
}
```
### 4.1. Константы
Константы класса ДОЛЖНЫ быть объявлены в верхнем регистре с подчеркиванием в качестве разделителей.
Пример:
```php
< ?php
class Foo
{
const VERSION = '1.0';
const DATE_APPROVED = '2012-06-01';
}
```
### 4.2. Свойства
- При объявлении общедоступных (public) членов класса нужно использовать ключевое слово `public` ;
- Общедоступные и защищенные (protected) переменные должны быть объявлены в начале класса, раньше объявления методов;
Закрытые (private) переменные, так же, должны быть объявлены в начале класса, но могут быть добавлены и непосредственно перед методами, использующими их, в случае, если эти переменные используются только небольшой частью методов класса;
- Порядок объявления свойств класса должен соответствовать их видимости: общедоступные, защищенные и закрытые;
- Ограничений на порядок свойств одной области видимости нет;
- Для улучшения читаемости, следует не оставлять пустых строк между объявлением свойств и оставлять две пустые строки между объявлениями переменных и методов. Между объявлениями свойств разной области видимости должна быть добавлена одна пустая строка;
- Закрытые переменные должны иметь имя вида `$_varName` ;
- Общедоступные члены класса и отдельные переменные должны использовать `$camelCase`
с первой буквой в нижнем регистре;
- Используйте понятные имена. Переменные вроде `$i` и `$j` лучше не использовать.
Пример:
```php
< ?php
class Foo
{
public $publicProp1;
public $publicProp2;
protected $protectedProp;
private $_privateProp;
public function someMethod()
{
// ...
}
}
```
### 4.3. Методы
- При именовании методов и функций следует использовать `camelCase` с первой буквой в нижнем регистре;
- Имена должны быть понятными и отражать назначение функции;
- Методы классов должны быть объявлены с использованием одного из модификаторов `private` , `protected` или
`public` . Использование `var` недопустимо;
- Открывающая фигурная кавычка должна быть расположена на строке, следующей за строкой объявления функции.
```php
/**
* Документация
*/
class Foo
{
/**
* Документация
*/
public function bar()
{
// код
return $value;
}
}
```
### 4.4 Блоки Документации
`@param` , `@var` , `@property` и `@return` должны описывать типы `bool` , `int` , `string` , `array` или `null` . Вы можете использовать и имена классов, например `Model` или `ActiveRecord` . Для типизированных массивов используйте `ClassName[]` .
### 4.5 Конструкторы
- Используйте `__construct` вместо старого стиля, применяемого в PHP 4.
## 5 PHP
### 5.1 Типы Данных
- Все типы данных и значения PHP должны быть в нижнем регистре. Это относится и к `true` , `false` , `null` и `array` .
Изменение типа существующей переменной считается плохой практикой. Постарайтесь не использовать такой подход, за исключением случаев, когда это действительно необходимо.
```php
public function save(Transaction $transaction, $argument2 = 100)
{
$transaction = new Connection; // плохо
$argument2 = 200; // хорошо
}
```
### 5.2 Строки
- Если строка не содержит переменных или одинарных кавычек, используйте одинарные кавычки;
```php
$str = 'Например так.';
```
- Если строка содержит одинарную кавычку, используйте двойные кавычки во избежание излишнего экранирования.
#### Подстановка переменных
```php
$str1 = "Привет, $username!";
$str2 = "Привет, {$username}!";
```
Следующий вариант запрещен:
```php
$str3 = "Привет, ${username}!";
```
#### Конкатенация
При конкатенации строк выделяйте точку пробелами:
```php
$name = 'Yii' . ' Framework';
```
Для длинных строк используйте следующий подход:
```php
$sql = "SELECT *"
. "FROM `post` "
. "WHERE `id` = 121 ";
```
### 5.3 Массивы
Для массивов мы используем краткий синтаксис, появившийся в PHP 5.4.
#### Индексированные массивы
- Не используйте отрицательные числа в качестве индексов массива.
Используйте следующий стиль:
```php
$arr = [3, 14, 15, 'Yii', 'Framework'];
```
При большом количестве элементов:
```php
$arr = [
3, 14, 15,
92, 6, $test,
'Yii', 'Framework',
];
```
#### Ассоциативные массивы
Для ассоциативных массивов используйте следующий стиль:
```php
$config = [
'name' => 'Yii',
'options' => ['usePHP' => true],
];
```
### 5.4 Управляющие конструкции
- Оставляйте один пробел перед открывающей круглой скобкой и после закрывающей круглой скобки в управляющих конструкциях;
- Операторы внутри круглых скобок должны разделяться пробелами;
- Открывающая фигурная скобка должна быть на той же строке;
- Закрывающая фигурная скобка должна быть на новой строке;
- Всегда используйте фигурные скобки для однострочных выражений.
```php
if ($event === null) {
return new Event();
}
if ($event instanceof CoolEvent) {
return $event->instance();
}
return null;
// такой код недопустим:
if (!$model & & null === $event)
throw new Exception('test');
```
Старайтесь избегать использования `else` после `return` там, где это возможно.
Используйте [граничные операторы ](https://refactoring.guru/ru/replace-nested-conditional-with-guard-clauses ).
```php
$result = $this->getResult();
if (empty($result)) {
return true;
} else {
// дальнейшие вычисления
}
```
лучше переписать так:
```php
$result = $this->getResult();
if (empty($result)) {
return true;
}
// дальнейшие вычисления
```
#### switch
Используйте следующий стиль для switch:
```php
switch ($this->phpType) {
case 'string':
$a = (string) $value;
break;
case 'integer':
case 'int':
$a = (int) $value;
break;
case 'boolean':
$a = (bool) $value;
break;
default:
$a = null;
}
```
### 5.5 Вызовы функций
```php
doIt(2, 3);
doIt(['a' => 'b']);
doIt('a', [
'a' => 'b',
'c' => 'd',
]);
```
### 5.6 Анонимные (lambda) функции
Не забывайте про пробелы между ключевыми словами `function` /`use` и открывающими круглыми скобками:
```php
// правильно
$n = 100;
$sum = array_reduce($numbers, function ($r, $x) use ($n) {
$this->doMagic();
$r += $x * $n;
return $r;
});
// неправильно
$n = 100;
$mul = array_reduce($numbers, function($r, $x) use($n) {
$this->doMagic();
$r *= $x * $n;
return $r;
});
```
Документация
-------------
- Для получения информации по синтаксису документации обратитесь к первоисточнику [PHPDoc ](http://phpdoc.org/ );
- Код без документации недопустим;
- Все файлы классов должны содержать блок документации в начале файла и блок документации непосредственно перед каждым классом;
- Нет необходимости использовать тег `@return` если метод не возвращает значение;
- Все виртуальные свойства классов, наследованных от `yii\base\BaseObject` , документируются тегом `@property` в блоке документации класса;
Аннотации геттеров и сеттеров автоматически генерируются из соответствующих тегов `@return` or `@param`
посредством выполнения команды `./build php-doc` в соответствующем каталоге;
Вы можете добавить дополнительный тег `@property` для геттера или сеттера для пояснения назначения переменной метода, если это необходимо.
Например:
```php
< ?php
/**
* Returns the errors for all attribute or a single attribute.
* @param string $attribute attribute name. Use `null` to retrieve errors for all attributes.
* @property array An array of errors for all attributes. Empty array is returned if no error.
* The result is a two-dimensional array. See [[getErrors()]] for detailed description.
* @return array errors for all attributes or the specified attribute. Empty array is returned if no error.
* Note that when returning errors for all attributes, the result is a two-dimensional array, like the following:
* ...
*/
public function getErrors($attribute = null)
```
#### Файл
```php
< ?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/
```
#### Класс
```php
/**
* Component is the base class that provides the *property* , *event* and *behavior* features.
*
* @include @yii/docs/base -Component.md
*
* @author Qiang Xue < qiang.xue @ gmail . com >
* @since 2.0
*/
class Component extends \yii\base\BaseObject
```
#### Функция / метод
```php
/**
* Returns the list of attached event handlers for an event.
* You may manipulate the returned [[Vector]] object by adding or removing handlers.
* For example,
*
* ```
* $component->getEventHandlers($eventName)->insertAt(0, $eventHandler);
* ```
*
* @param string $name the event name
* @return Vector list of attached event handlers for the event
* @throws Exception if the event is not defined
*/
public function getEventHandlers($name)
{
if (!isset($this->_e[$name])) {
$this->_e[$name] = new Vector;
}
$this->ensureBehaviors();
return $this->_e[$name];
}
```
#### Разметка
Как вы можете видеть в примерах выше, мы используем специальную разметку для форматирования комментариев PHPDoc.
Ниже описан дополнительный синтаксис для описания связей между классами, методами и свойствами в документации:
- `[[canSetProperty]]` создаст ссылку на метод или свойство `canSetProperty` этого класса;
- `[[Component::canSetProperty]]` создаст ссылку на метод `canSetProperty` класса `Component` того же пространства имен;
- `[[yii\base\Component::canSetProperty]]` создаст ссылку на метод `canSetProperty` класса `Component` в пространстве имен `yii\base` ;
- `[[Component]]` создаст ссылку на класс `Component` в том же пространстве имен. Здесь так же возможно явное указание пространства имен.
Для явного указания текста ссылки возможно использование следующего синтаксиса:
```
... as displayed in the [[header|header cell]].
```
Часть до | это имя свойства, метода или класса для ссылки, а часто поле | это текст ссылки.
Так же, возможно создание ссылок на Руководство:
```markdown
[Руководство ](guide:file-name.md )
[Раздел руководства ](guide:file-name.md#subsection )
```
#### Комментарии
- Однострочные комментарии должны начинаться с `//` , а не с `#` ;
- Однострочные комментарии должны располагаться на отдельной строке.
Дополнительные правила
----------------
### `=== []` или `empty()`
Используйте `empty()` , где это возможно.
### Несколько точек возврата
Не допускайте запутанных вложенных условных конструкций, используйте return. Для коротких методов это не актуально.
### `self` или `static`
Всегда используйте `static` , за исключением следующих случаев:
- доступ к константам ДОЛЖЕН осуществляться через `self` : `self::MY_CONSTANT` ;
- доступ к защищенным статическим свойствам ДОЛЖЕН осуществляться через `self` : `self::$_events` ;
- допустимо использовать `self` для рекурсивного обращения к текущему классу, вместо класса наследника.
### Значение "ничего не делать"
Свойства указывающее компоненту на отсутствие необходимости что-либо делать, должны принимать значение `false` . `Null` , `''` , или `[]` не должны использоваться в таких случаях.
### Каталоги/пространства имен
- Используйте нижний регистр;
- используйте множественное число для существительных, представляющих объекты (например валидаторы);
- используйте единственное число для имен, представляющих соответствующий функционал (например web);
- предпочтительнее использовать однословные пространства имён;
- если одно слово использовать не удаётся, используйте camelCase стиль.