Skip to content

Latest commit

 

History

History
183 lines (129 loc) · 7.76 KB

PSR-1-basic-coding-standard.md

File metadata and controls

183 lines (129 loc) · 7.76 KB
Raw

Основной стандарт кодирования

Этот раздел стандарта описывает какие элементы кода следует считать стандартными, необходимыми для обеспечения высокого уровня технического взаимодействия между общим (разделяемым) кодом PHP.

Ключевые слова «НЕОБХОДИМО»/«ДОЛЖНО» («MUST»), «НЕДОПУСТИМО»/«НЕ ДОЛЖНО» («MUST NOT»), «ТРЕБУЕТСЯ» («REQUIRED»), «НУЖНО» («SHALL»), «НЕ ПОЗВОЛЯЕТСЯ» («SHALL NOT»), «СЛЕДУЕТ» («SHOULD»), «НЕ СЛЕДУЕТ» («SHOULD NOT»), «РЕКОМЕНДУЕТСЯ» («RECOMMENDED»), «ВОЗМОЖНО» («MAY») и «НЕОБЯЗАТЕЛЬНО» («OPTIONAL») в этом документе должны расцениваться так, как описано в RFC 2119.

  1. Обзор

  • В файлах НЕОБХОДИМО использовать только теги <?php и <?=.

  • В файлах с кодом PHP НЕОБХОДИМО использовать только UTF-8 без BOM.

  • В одном файле СЛЕДУЕТ либо объявлять символы (классы, функции, константы и т. д.), либо выполнять побочные действия (т. е. производить вывод, менять значения .ini и т. д.), но НЕ СЛЕДУЕТ делать и то и другое одновременно.

  • НЕОБХОДИМО, чтобы пространства имён и классы соответствовали стандартам PSR, описывающим автозагрузку: [PSR-0, PSR-4].

  • Классам НЕОБХОДИМО давать имена в стиле StudlyCaps.

  • Константам классов НЕОБХОДИМО давать имена в верхнем регистре с символом подчёркивания в качестве разделителя.

  • Методам НЕОБХОДИМО давать имена в стиле camelCase.

  1. Файлы

2.1. Теги PHP

В коде PHP НЕОБХОДИМО использовать полные теги <?php или сокращённую форму <?=. Использование других вариантов тегов НЕДОПУСТИМО.

2.2. Кодировка символов

Для кода PHP НЕОБХОДИМО использовать только UTF-8 без BOM.

2.3. Побочные действия

В файле СЛЕДУЕТ объявлять новые символы (классы, функции, константы и т. д.) не выполняя побочных действий, либо СЛЕДУЕТ выполнять логику, но НЕ СЛЕДУЕТ делать и то и другое сразу.

Выражение «побочные действия» означает выполнение при подключении файла действий, не связанных напрямую с объявлением классов, функций, констант и т. д.

«Побочные действия» включают в себя (но не ограничиваются): генерацию вывода, явное использование 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()
    {
        // тело функции
    }
}
  1. Пространства имён и имена классов

НЕОБХОДИМО, чтобы пространства имён и классы соответствовали стандартам "автозагрузки" [PSR-0, PSR-4].

Это значит что каждый класс должен располагаться в отдельном файле и находиться в пространстве имён как минимум первого уровня — соответствующем названию разработчика.

Классам НЕОБХОДИМО давать имена в стиле StudlyCaps.

В коде, написанном для PHP версий 5.3 и новее, НЕОБХОДИМО использовать формальные пространства имён.

Пример:

<?php
// PHP 5.3 и новее:
namespace Vendor\Model;

class Foo
{
}

В коде, написанном для PHP версий 5.2.x и более ранних, СЛЕДУЕТ использовать соглашение о псевдо-пространствах имён с использованием префикса Vendor_ в именах классов.

<?php
// PHP 5.2.x и более ранние:
class Vendor_Model_Foo
{
}
  1. Константы классов, свойства и методы

Понятие «класс» относится ко всем классам, интерфейсам и трейтам.

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().