mirror of
https://github.com/yiisoft/yii2.git
synced 2025-08-15 14:50:56 +08:00
476 lines
21 KiB
Markdown
476 lines
21 KiB
Markdown
Стиль кодирования 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 стиль.
|