Обрамлення PHP коду

В PHP-коді можна використовувати лише <?php та <?= (short-echo). Використання <?, <% та <script language="php"> забороняється. Закриваючий тег ?> обов'язковий для шаблонних файлів. У файлах де використовується лише одна вставка PHP-коду (файли класів) допускається його пропуск.

<h1>Site name</h1>
<?php include 'menu.php'; // поганий стиль

<h1>Site name</h1>
<? include 'menu.php'; // поганий стиль

<h1>Site name</h1>
<?php
include 'menu.php'; // хороший стиль
?>

<?php // хороший стиль
class UserController {

}

Коментарi

Коментарi всередині кода класів повинні відповідати синтаксису коментарів PHPDoc (http://www.phpdoc.org)

<?php
// хороший стиль
// одностроковий коментар
/*
 * багатостроковий коментар
 */

// поганий стиль
# тип коментаря використовувати не рекомендується

Управляючі структури

Використовуйте фігурні дужки в керуючих струкрутурах навіть тоді, коли вони не є обов'язковими:

// поганий стиль
if (isset($name))
    echo "Hello $name";

// хороший стиль
if (isset($name)) {
    echo "Hello $name";
}

Використовуйте K&R стиль фігурних дужок. В керуючих структурах між ключовим словом та відкриваючою круглою дужкою повинен знаходитись пробіл, щоб відрізняти їх від виклику функцій.

<?php
// поганий стиль
if((condition1)||(condition2)) {
    action1;
}elseif((condition3)&&(condition4)){
    action2;
}else{
    defaultaction;
}

// хороший стиль
if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}
?>

Якщо умовний вираз перевищує деяку умовну довжину строки, потрібно розбити його на декілька стрічок. В такому випадку, переносимо до логічного оператора та вирівнюємо пробіламі до першого символа умовного виразу. Закриваюча дужка повинна бути на новій строці з рівнем відступа як у керуючої структури на тій же строці.

<?php
if (($a == $b)
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
}
?>

Стрічки

Стрiчкові літерали

Якщо стрічка є літеральною (не має підстановок змінних), для її обрамлення повинні використовуватись апострофи ("одинарні лапки")

<?php
$a = 'Simple String';
?>

Підстановка змінних

<?php
// поганий стиль
$greeting = "Hello ${username}!";

// хороший стиль
$greeting = "Hello $username!";
$greeting = "Hello {$username}!";
?>

Конкатенація стрічок

Cтрічки повинні об'єднуватись за допомогою оператора ".". Пробіл повинен завжді додаватись до та після оператора "." для покращення читабельності:

$greeting = "Hello " . $username . " !";

Коли відбувається конкатенація стрічок за допомогод оператора ".", дозволяється розривати вираз на декілька стрічок для покращення читабельності. В цьому випадку, кожна стрічка повинна доповнюватись пробілами так, щоб оператор "." був вирівняний під оператором "=":

$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";

Багаторядкові стрічки

Для запису багаторядкової стрічки необхідно користуватися HEREDOC. Якщо є вставка іншої мови, то необхідно її вказати.

$string = <<<HEREDOC
Просто стрічка
HEREDOC;

$html = <<<HTML
<h1>Title</h1>
HTML;

Масиви

Масиви з числовими індексами

Коли визначаютсья індексований масив за допомогою конструкції Array , завершуючий пробіл повинен бути добавлений після кожної коми для покращення читабельності:

$sampleArray = array(1, 2, 3, 'Zend', 'Studio');

Також дозволяється визначати многострочні індексовані масиви, використовуючи конструкцію "array". В цьому випадку, кожна наступна строка повинна бути доповнена пробілами так, щоб початок кожної наступної стрічки був вирівняний як показано нижче:

$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500);

Альтернативно можна розглядати наступний запис масиву

$sampleArray = array(
    1, 2, 3, 'Zend', 'Studio',
    $a, $b, $c,
    56.44, $d, 500,
);

Асоціативні масиви

Коли визначається асоціативний масив за допомогою конструкції Array , рекомендовано розділяти вираз на декілька стрічок. В цьому випадку, кожна наступна стрічка повинна бути доповнена пробілами так, щоб її ключі та значення були вирівняні:

$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');

Ще один варіант запису асоціативних масивів:

$sampleArray = array(
    'firstKey'  => 'firstValue',
    'secondKey' => 'secondValue',
);

Функції

Визначення функцій

Визначення функцій повинно слідувати наступному стилю:

<?php
function fooFunction($arg1, $arg2 = '')
{
    if (condition) {
        statement;
    }
    return $val;
}
?>

Аргументи функції за замовчуванням повинні знаходитись в кінці списку аргументів. Функції завжди повинні повертати значення, якщо це можливо в принципі.

<?php
function connect(&$dsn, $persistent = false)
{
    if (is_array($dsn)) {
        $dsninfo = &$dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);
    }

    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();
    }

    return true;
}
?>

Класи

Визначення класа

Фігурна дужка завжди пишеться на слідуючій строці під іменем класу.

Кожен клас повиенен мати блок документації (doc-блок) в відповідності до стандарту PHPDocumentor.

Тільки один клас дозволений всередині одного PHP-файлу.

Розміщення додаткового кода в файлі з класом дозволено, але не рекомендується. В таких файлах, дві пустих строки повинні розділяри клас та доповнювати PHP-код.

Приклад допустимого визначення класу:

/**
* Doc-блок здесь
*/
class SampleClass
{
    // содержимое класса должно быть
    // с отступом в четыре пробела
}

Класи, розширюючі інші класи або реалізуючі інтерфейси, повинні об'являти свої залежності на тій же строці, якщо це можливо.

class SampleClass extends FooAbstract implements BarInterface
{
}

Якщо довижина такого об'явлення, довжина строки перевищує максимальну довжину строки (80 символів), то потрібно зробити перенос перед ключовими словами "extends" та/або "implements" і зробити відступ в один рівень.

class SampleClass
    extends FooAbstract
    implements BarInterface
{
}

Якщо клас реалізує декілька інтерфейсів та об'явлення перевищує максимальну довжину строки (80 символів) - зробіть перенос після коми, розділяючої інтерфейси та вирівняйте їх імена робілами:

class SampleClass
    implements BarInterface,
               BazInterface
{
}

Змінні члени-класів

Будь-які змінні, визначені в класі, повинні бути описані на початку класу, до визначення будь-якого методу.

Ключове слово var не дозволяється. Члени класа повинні завжди виділяти їх область видимості, викоритсовуючи ключове слово private, protected или public.

Іменування

Константі та глобальні змінні

Імена констант та глобальних змінних завжди повинні бути в верхньому регістрі з підкреслюваннямі для розділення слів. В якості префікса в іменах констант повинно використовуватись ім'я класа, в якому вони викоритовуються.

$CACHE_PATH

Вбудовані константи TRUE, FALSE, NULL

Вбудовані константі PHP TRUE, FALSE та NULL повинні бути написані в ніжньому регістрі.

true

Тимчасові змінні та «плаваючі функції»

Імена тимчасових змінних та «плаваючих функцій» завжди повинні бути в нижньому регістрі з підкеслюваннями для розділення слів. Функції також повинні мати префікс в вігляді імені пакета для того, щоб уникнути проблем з аналогічними функціямі з інших пакетів.

$num_elements
RPC_serialize_data()

Імена методів та властивостей

Методі та властівості класів повинні використовувати «угорську нотацію». Перша літера в імені повинна бути в нижньому регістрі, кожна перша буква «слова» в імені - в верхньому. Знак підкреслювання заборонений.

getData()
$this->currentStatus

Приватні методи та властивості повинні бути префіксовані знаком підкреслювання

_sort()
_initTree()
$this->_status

Імена класів

Перша літера імені класу повинна бути в верхньому регістрі, символи підкреслювання повинні використовуватись лиш для імітмції вкладеності простору імен, багатослівні імена класів повинні представляти собою одне слово, а перші літери всіх входящіх в ім'я слів повинні бути в верхньмоу регістрі (тобто з використанням угорської нотації).

class XML_RSS {}
class Text_PrettyPrinter {}

Параметри файлу

Файл має використовувати розширення .php та кодування UTF-8 без BOM.

yiiworld / style-guide-php Goto Github PK

style-guide-php's Introduction