Описанный ниже стиль кодирования используется при разработке ядра 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` или `<?=`;
- Для выравнивания кода НУЖНО использовать 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\Object 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` должны описывать типы `boolean`, `integer`, `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` там, где это возможно.
Свойства указывающее компоненту на отсутствие необходимости что-либо делать, должны принимать значение `false`. `Null`, `''`, или `[]` не должны использоваться в таких случаях.
