Перейти до основного вмісту

PSR-1 Базовий стандарт стилю кодування

Цей розділ стандарту містить елементи кодування, які слід вважати стандартними та необхідними для забезпечення високого рівня технічної взаємодії між спільним PHP-кодом.

Ключові слова «ОБОВ'ЯЗКОВО», «НЕ ПРИПУСТИМО», «ВИМАГАЄТЬСЯ», «ПОВИНЕН», «ЗАБОРОНЯЄТЬСЯ», «РЕКОМЕНДОВАНО», «НЕ РЕКОМЕНДОВАНО», «СЛІДУЄ», «МОЖЛИВО» та «ОПЦІОНАЛЬНО» у цьому документі слід трактувати так, як описано у RFC 2119.

1. Огляд​

  • У файлах ОБОВ'ЯЗКОВО використовувати тільки теги <?php та <?=.
  • У файлах ОБОВ'ЯЗКОВО використовувати тільки UTF-8 без BOM для PHP-коду.
  • У файлах РЕКОМЕНДОВАНО або оголошувати символи (класи, функції, константи тощо), або викликати побічні ефекти (наприклад, генерувати вивід, змінювати налаштування .ini тощо), але НЕ РЕКОМЕНДОВАНО робити обидві речі одночасно.
  • У просторі імен та класах ОБОВ'ЯЗКОВО дотримуватися PSR "автозавантаження": [PSR-0, PSR-4].
  • Назви класів ОБОВ'ЯЗКОВО оголошувати в StudlyCaps.
  • Константи класу ОБОВ'ЯЗКОВО оголошувати в верхньому регістрі з роздільниками підкреслення.
  • Назви методів ОБОВ'ЯЗКОВО оголошувати в camelCase.

2. Файли​

2.1. Теги PHP​

У коді PHP ОБОВ'ЯЗКОВО використовувати довгі теги <?php ?> або короткі-вивід <?= ?>, і НЕ ПРИПУСТИМО використовувати інші варіанти тегів.

2.2. Кодування символів​

У коді PHP ОБОВ'ЯЗКОВО використовувати тільки UTF-8 без BOM.

2.3. Побічні ефекти​

Побічний ефект - wikipedia
Побічний ефект - wikipedia

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

Побічні ефекти — найзвичніший спосіб взаємодії з зовнішнім світом (людьми, файловою системою, іншими комп'ютерами в мережі). Ступінь використання побічних ефектів залежить від парадигми програмування. Імперативне програмування відоме частим використанням побічних ефектів. У функціональному програмуванні побічні ефекти використовують зрідка. Функціональні мови такі як Standard ML або Scheme не забороняють побічні ефекти, але зазвичай програмісти уникають їх. Функціональна мова Haskell обмежує побічні ефекти через статичну систему типізації; вона використовує концепцію монад.

Розробники користуючись мовою асемблера мають зважати на приховані побічні ефекти — інструкції, які змінюють частину стану процесора без зазначення цього в своїх назвах. Класичний приклад прихованого побічного ефекту — арифметична інструкція, яка явно змінює регістр (явний ефект (англ. overt effect)) і неявно змінює коди умов (прихований побічний ефект). Наприклад, прапорці, що вказують на те, що в результаті отримано нуль або переповнення. Один з недоліків набору інструкцій з багатьма побічними ефектами полягає в можливості впливу на одну частинку стану, наприклад коди умов, тоді коли вимога оновлювати ці стани послідовно може стати вузьким місцем швидкодії. Проблема постає особливо гостро на процесорах розроблених з конвеєром команд (з 1990) або з позачерговим виконанням. Такі процесори можуть потребувати додаткову схему для перевірки на побічні ефекти і зупиняти конвеєр, якщо наступна інструкція залежить від наслідків цих ефектів.

У файлі РЕКОМЕНДОВАНО оголошувати нові (класи, функції, константи тощо) і не мати інших побічних ефектів, або РЕКОМЕНДОВАНО виконувати логіку з побічними ефектами, але НЕ РЕКОМЕНДОВАНО робити обидві речі одночасно.

Фраза "побічні ефекти" означає виконання логіки, що не пов'язана безпосередньо з оголошенням класів, функцій, констант тощо, лише в результаті включення файлу.

"Побічні ефекти" включають, але не обмежуються: генеруванням виводу, явним використанням require або include, підключенням до зовнішніх сервісів, зміною налаштувань ini, викиданням помилок або винятків, зміною глобальних або статичних змінних, зчитуванням з файлу або записом до файлу і т.д.

Наведено приклад файлу з оголошеннями та побічними ефектами; тобто, приклад того, що слід уникати:

<?php
// побічний ефект: змінює ini налаштування
ini_set('error_reporting', E_ALL);

// побічний ефект: завантажує файл
include "file.php";

// побічний ефект: генерує вивід
echo "<html>\n";

// оголошення
function foo()
{
    // тіло функції
}

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

<?php
// оголошення
function foo()
{
    // тіло функції
}

// умовне оголошення *не* є побічним ефектом
if (! function_exists('bar')) {
    function bar()
    {
        // тіло функції
    }
}

3. Простори імен та імена класів​

Простори імен та класи ОБОВ'ЯЗКОВО щоб відповідали стандарту PSR "автозавантаження": [PSR-0, PSR-4].

Це означає, що кожен клас знаходиться у власному файлі та знаходиться в просторі імен, що складається щонайменше з одного рівня: назви виробника на верхньому рівні.

Імена класів ОБОВ'ЯЗКОВО оформлювати за допомогою StudlyCaps.

У коді, написаний для PHP 5.3 і пізніших версій, ОБОВ'ЯЗКОВО використовувати формальні простори імен.

Наприклад:

<?php
// PHP 5.3 і вище:
namespace Vendor\Model;

class Foo
{
}

У коді написаному для 5.2.x і раніших версій РЕКОМЕНДОВАНО використовувати угоду про псевдопростір імен префіксів Vendor_ в іменах класів.

<?php
// PHP 5.2.x і нижче:
class Vendor_Model_Foo
{
}

4. Константи, властивості та методи класу​

Термін "клас" охоплює всі класи, інтерфейси та трейти.

4.1. Константи​

Константи класу ОБОВ'ЯЗКОВО оголошувати в верхньому регістрі з роздільниками підкреслення. Наприклад:

<?php
namespace Vendor\Model;

class Foo
{
    const VERSION = '1.0';
    const DATE_APPROVED = '2012-06-01';
}

4.2. Властивості​

Це керівництво навмисно уникає будь-яких рекомендацій щодо використання імен властивостей $StudlyCaps, $camelCase або $under_score.

Будь-яка конвенція найменування, що використовується, РЕКОМЕНДОВАНО застосовувати послідовно в межах розумного обсягу. Цей обсяг може бути на рівні вендора, пакета, класу або методу.

4.3. Методи​

Назви методів ОБОВ'ЯЗКОВО оголошувати в camelCase().