docs/internals-uk/core-code-style.md
Нижченаведений стиль кодування використовується у розробці основного коду Yii 2.x та офіційних розширень. Дотримуйтесь його, якщо хочете вносити зміни в основний код. Команда розробників не наполягає на використанні цього стилю для вашого додатка. Вільно обирайте те, що підходить вам більше.
Ви можете отримати конфігурацію для CodeSniffer за посиланням: https://github.com/yiisoft/yii2-coding-standards
В основному командою розробників використовується стиль сумісний з PSR-2, тому все, що стосується PSR-2, застосовується також.
<?php або <?=.StudlyCaps.camelCase.camelCase.elseif замість else if.<?php ?> або <?=; він НЕ ПОВИНЕН використовувати інші варіації, такі як <?.?>..php.PHP код ПОВИНЕН використовувати лише UTF-8 без BOM.
Імена класів ПОВИННІ оголошуватись як StudlyCaps. Наприклад: Controller, Model.
Тут термін "клас" відноситься до всіх класів та інтерфейсів.
CamelCase./**
* Документація
*/
class MyClass extends \yii\base\BaseObject implements MyInterface
{
// код
}
Імена констант ПОВИННІ оголошуватись повністю у верхньому регістрі, підкреслення використовується як роздільник. Наприклад:
<?php
class Foo
{
const VERSION = '1.0';
const DATE_APPROVED = '2012-06-01';
}
public.$_varName.$camelCase
(перша літера у нижньому регістрі).$i та $j, краще не використовувати.Наприклад:
<?php
class Foo
{
public $publicProp;
protected $protectedProp;
private $_privateProp;
}
camelCase (перша літера у нижньому регістрі).private, protected та
public. Не допускається використання var./**
* Документація
*/
class Foo
{
/**
* Документація
*/
public function bar()
{
// код
return $value;
}
}
@param, @var, @property та @return повинні оголошувати типи як bool, int, string, array чи null. Також можна використовувати імена класів, як наприклад: Model або ActiveRecord. Для типізованих масивів використовуйте ClassName[].
__construct замість стилю конструкторів PHP 4.true, false, null та array.Зміна типу змінної, що вже існує, вважається поганою практикою. Намагайтесь не писати такий код, поки в цьому дійсно нема потреби.
public function save(Transaction $transaction, $argument2 = 100)
{
$transaction = new Connection; // погано
$argument2 = 200; // добре
}
$str = 'Текстовий рядок.';
$str1 = "Привіт, $username!";
$str2 = "Привіт, {$username}!";
Нижченаведений приклад не допускається:
$str3 = "Привіт, ${username}!";
Додавайте пробіли навколо оператора конкатенації (.), коли об’єднуєте текстові рядки:
$name = 'Фреймворк ' . 'Yii';
Для довгих текстових рядків використовуйте наступний формат:
$sql = "SELECT *"
. "FROM `post` "
. "WHERE `id` = 121 ";
Для масивів використовуйте скорочений синтаксис (PHP 5.4).
Використовуйте нижченаведений формат оголошення масиву:
$arr = [3, 14, 15, 'Yii', 'фреймворк'];
Якщо забагато елементів для одного рядка:
$arr = [
3, 14, 15,
92, 6, $test,
'Yii', 'фреймворк',
];
Використовуйте нижченаведений формат для асоціативних масивів:
$config = [
'name' => 'Yii',
'options' => ['usePHP' => true],
];
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, де це має сенс.
Використовуйте вартові умови.
$result = $this->getResult();
if (empty($result)) {
return true;
} else {
// обробка результату
}
буде краще так:
$result = $this->getResult();
if (empty($result)) {
return true;
}
// обробка результату
Використовуйте наступний формат для switch:
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;
}
doIt(2, 3);
doIt(['a' => 'b']);
doIt('a', [
'a' => 'b',
'c' => 'd',
]);
Зверніть увагу на пробіл між function/use та початковою круглою дужкою:
// добре
$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 для довідки про синтаксис документації.
Код без документації не допускається.
Усі файли класів повинні містити файловий ("file-level") doc-блок на початку та класовий ("class-level") doc-блок безпосередньо над кожним класом.
Нема потреби використовувати @return, якщо метод нічого не повертає.
Усі віртуальні властивості у класах успадкованих від yii\base\BaseObject
документуються з тегом @property у класовому doc-блоці.
Ці анотації генеруються автоматично із тегів @return чи @param
відповідних геттерів або сеттерів виконанням команди ./build php-doc у директорії build.
Ви можете додати тег @property
до геттеру або сеттеру, щоб точно визначити повідомлення для документації властивості,
яка представляється цими методами, коли опис відрізняється від того, що встановлено
тегом @return. Наприклад:
<?php
/**
* Returns the errors for all attributes 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
/**
* @link https://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license https://www.yiiframework.com/license/
*/
/**
* 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
/**
* 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 використовується markdown.
Існує додатковий синтаксис для створення перехресних посилань між класами, методами та властивостями у документації:
[[canSetProperty]] створить посилання на метод або властивість canSetProperty того ж самого класу.[[Component::canSetProperty]] створить посилання на метод canSetProperty класу Component в тому ж самому просторі імен.[[yii\base\Component::canSetProperty]] створить посилання на метод canSetProperty класу Component з простору імен yii\base.[[Component]] створить посилання на клас Component в тому ж самому просторі імен. Додавання простору імен до імені класу тут також можливе.Щоб для одного з вище зазначених посилань вказати мітку відмінну від імені класу чи методу, ви можете використовувати синтаксис, показаний в нижченаведеному прикладі:
... as displayed in the [[header|header cell]].
Частина перед | є найменуванням методу, властивості або класу, в той час як частина після | є міткою посилання.
Також можливо посилатись на Посібник, використовуючи наступний синтаксис:
[link to guide](guide:file-name.md)
[link to guide](guide:file-name.md#subsection)
//, а не з #.=== [] проти empty()Використовуйте empty(), де можливо.
При великій вкладеності умов, використовуйте інструкцію return раніше. Якщо метод не великий, це неважливо.
self проти staticЗавжди використовуйте static, за виключенням наведених випадків:
self: self::MY_CONSTANTself: self::$_eventsself для рекурсії, щоб викликати поточне втілення знову замість розширення реалізації класу.Властивості, яким дозволено сконфігурувати компонент не робити чогось, повинні приймати значення false. Значення null, '' чи [] не повинні вважатись такими.