Стандарт PSR-12 на русском для PHP-разработчиков | Работа в Redwerk
Стандарт PSR-12 на русском для PHP-разработчиков

Стандарт PSR-12 на русском для PHP-разработчиков

Декабрь 11, 2019

Предисловие

PHP Standarts Recommendations — это рекомендации для PHP-разработчиков, разработанные PHP Framework Interop Group. Задача рекомендаций — помочь программистам унифицировать решения некоторых задач.

Redwerk.jobs первым сделал для вас перевод PSR-12. Соглашаться ли с рекомендациями — решать вам.

Общие положения

Ключевые слова «ДОЛЖНО», «НЕ ДОЛЖНО», «ТРЕБУЕТСЯ», «СЛЕДУЕТ», «НЕ СЛЕДУЕТ», «РЕКОМЕНДУЕТСЯ», «МОЖЕТ» и «НЕОБЯЗАТЕЛЬНЫЙ» в этом документе следует интерпретировать как описано в RFC 2119.

Эта спецификация расширяет и заменяет PSR-2, руководство по стилю кодирования, и требует соблюдения PSR-1, базового стандарта оформления кода.

Как и PSR-2, цель этой спецификации — упростить читаемость кода и убрать разногласия между разными авторами. Это достигается путем перечисления общего набора правил и ожиданий о том, как будет сформирован код PHP. Этот PSR предоставляет набор инструкций, которых могут придерживаться инструменты для форматирования, а разработчики могут легко установить связь между различными проектами. Когда различные авторы сотрудничают внутри одного проектами, это поможет иметь один набор руководящих принципов, который будет использоваться внутри проектов. Таким образом, преимущество этого руководства заключается не в самих правилах, а в совместном их использовании.

PSR-2 был принят в 2012 году, и с тех пор в PHP был внесен ряд изменений, которые повлияли на рекомендации по стилю кодирования. В то время как PSR-2 является довольно полным набором функционала PHP, который существовал на момент написания, новый функционал можно интерпретировать по-разному. Таким образом, этот PSR стремится прояснить содержание PSR-2 в более современном контексте, учитывая новые функциональные возможности.

Предыдущие версии языка

В этом документе любые инструкции МОГУТ быть проигнорированы, если они не существуют в версиях PHP, поддерживаемых вашим проектом.

Пример

Этот пример охватывает некоторые из приведенных ниже правил в качестве краткого обзора:

2. Общие

2.1 Базовый стандарт написания кода

Код ДОЛЖЕН соответствовать всем правилам, изложенным в PSR-1.

Термин «StudlyCaps» в PSR-1 ДОЛЖЕН интерпретироваться как PascalCase, где первая буква каждого слова пишется с большой буквы, включая самую первую букву.

2.2 Файлы

Все файлы PHP ДОЛЖНЫ использовать только Unix LF (linefeed) в конец строки.

Все файлы PHP ДОЛЖНЫ заканчиваться непустой строкой, с одним LF в конце.

Закрывающий тег ?> ДОЛЖЕН быть исключен в файлах, содержащих только PHP.

2.3 Линии

НЕ ДОЛЖНО быть жесткого ограничения (hard limit) на длину строки.

Мягкое ограничение (soft limit) на длину строки ДОЛЖНО быть 120 символов.

Строки НЕ ДОЛЖНЫ быть длиннее 80 символов; строки, длина которых превышает эту длину, ДОЛЖНЫ разбиваться на несколько последующих строк длиной не более 80 символов.

НЕ ДОЛЖНО быть пробелов в конце строк.

Пустые строки МОГУТ быть добавлены для улучшения читабельности и для обозначения связанных блоков кода, за исключением случаев, когда это запрещено.

НЕ ДОЛЖНО быть более одного оператора на строку.

2.4 Отступ

Код ДОЛЖЕН использовать отступ в 4 пробела для каждого уровня отступа и НЕ ДОЛЖЕН использовать табуляцию для отступа.

2.5 Ключевые слова и виды

Все ключевые слова и типы PHP [1] [2] ДОЛЖНЫ быть в нижнем регистре.

Любые новые виды и ключевые слова, добавленные в будущие версии PHP, ДОЛЖНЫ быть в нижнем регистре.

НЕОБХОДИМО использовать краткую форму ключевых слов, то есть bool вместо boolean, int вместо integer и т. д.

3. Оператор Declare, Namespace и операторы Import

Заголовок файла PHP может состоять из нескольких различных блоков. Каждый следующий блок ДОЛЖЕН быть разделен одной пустой строкой и НЕ ДОЛЖЕН содержать пустую строку. Каждый блок ДОЛЖЕН быть в указанном ниже порядке, хотя нерелевантные блоки могут быть исключены.

  • Открытие тега <?php.
  • Файловый doc-блок.
  • Один или несколько операторов declare.
  • Пространства имен файла.
  • Один или несколько импорт операторов use на основе классов.
  • Один или несколько импорт операторов use на основе функций.
  • Один или несколько use операторов import на основе констант.
  • Остальная часть кода в файле.

Если файл содержит HTML и PHP, любой из вышеперечисленных разделов все еще может использоваться. Если это так, они ДОЛЖНЫ присутствовать в верхней части файла, даже если остальная часть кода состоит из закрывающего тега PHP, а затем представляет собой смесь HTML и PHP.

Когда открывающий тег <?php находится в первой строке файла, он ДОЛЖЕН находиться в отдельной строке без других операторов, если это не файл, содержащий разметку вне открывающих и закрывающих тегов PHP.

Операторы import НЕ ДОЛЖНЫ начинаться с обратной косой черты, поскольку они всегда должны быть полностью уточненный (qualified).

Следующий пример иллюстрирует полный список всех блоков:

Составные пространства имен с глубиной более двух НЕ ДОЛЖНЫ использоваться. Поэтому максимально допустимая глубина вложенности:

И не разрешено следующее:

При желании объявить строгие типы в файлах, содержащих разметку вне открывающих и закрывающих тегов PHP, объявление ДОЛЖНО быть в первой строке файла и включать открывающий тег PHP, объявление строгих типов, и закрывающий тег.

Например:

Операторы объявления НЕ ДОЛЖНЫ содержать пробелы и ДОЛЖНЫ быть такими: declare(strict_types=1) (с необязательным ограничителем точки с запятой).

Операторы объявления блоков допускаются и ДОЛЖНЫ быть отформатированы, как показано ниже. Обратите внимание на положение фигурных скобок и интервалов:

4. Классы, свойства, и методы

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

Любая закрывающая скобка НЕ ДОЛЖНА сопровождаться комментариями или утверждениями в той же строке.

При создании нового класса круглые скобки ДОЛЖНЫ присутствовать всегда, даже если в конструктор не переданы аргументы.

4.1 Ключевые слова Extends и Implements

НЕОБХОДИМО, чтобы ключевые слова extends и implements были объявлены в той же строке, что и имя класса.

Открывающая скобка для класса ДОЛЖНА находиться на своей собственной строке, а закрывающая скобка для класса ДОЛЖНА находиться на следующей строке после тела.

Открывающие фигурные скобки ДОЛЖНЫ находиться на своей собственной строке и НЕ ДОЛЖНЫ предшествовать или сопровождаться пустой строкой.

Закрывающие фигурные скобки ДОЛЖНЫ находиться на своей собственной строке и НЕ ДОЛЖНЫ предшествовать пустой строке.

Списки implements и, в случае интерфейсов, extends МОГУТ быть разбиты на несколько строк, где каждая последующая строка имеет один отступ. При этом первый элемент в списке ДОЛЖЕН быть на следующей строке, и ДОЛЖЕН быть только один интерфейс на строку.

4.2 Использование трейтов (traits)

Ключевое слово use, используемое внутри классов для реализации признаков, ДОЛЖНО быть объявлено на следующей строке после открывающей скобки.

Каждый отдельный трейт, который импортируется в класс, ДОЛЖЕН быть включен по одному на строку, и каждое включение ДОЛЖНО иметь свой собственный импорт оператор use.

Когда у класса нет ничего после импорт оператора use, закрывающая скобка класса ДОЛЖНА находиться на следующей строке после импорт оператора use.

В противном случае он ДОЛЖЕН иметь пустую строку после импорт оператора use.

При использовании операторов insteadof и as они должны использоваться следующим образом, принимая во внимание отступы, интервалы, и новые строки.

4.3 Свойства и константы

Видимость ДОЛЖНА быть объявлена на всех свойствах.

Видимость ДОЛЖНА быть объявлена для всех констант, если минимальная версия PHP вашего проекта поддерживает постоянные видимости (PHP 7.1 или более поздняя версия).

Ключевое слово var НЕ ДОЛЖНО использоваться для объявления свойства.

НЕ ДОЛЖНО быть более одного свойства, объявленного на утверждение.

Имена свойств НЕ ДОЛЖНЫ иметь префикс с одним подчеркиванием для обозначения защищенной или приватной видимости. То есть префикс подчеркивания явно не имеет значения.

ДОЛЖЕН быть пробел между объявлением типа и именем свойства.

Объявление свойства выглядит следующим образом:

4.4 Методы и функции

Видимость ДОЛЖНА быть объявлена во всех методах.

Имена методов НЕ ДОЛЖНЫ иметь префикс с одним подчеркиванием для обозначения защищенной или приватной видимости. То есть префикс подчеркивания явно не имеет значения.

Имена методов и функций НЕ ДОЛЖНЫ быть объявлены с пробелом после имени метода. Открывающая фигурная скобка ДОЛЖНА находиться на отдельной строке, а закрывающая фигурная скобка ДОЛЖНА находиться на следующей строке после тела. НЕ ДОЛЖНО быть пробела после открывающей скобки, и НЕ ДОЛЖНО быть пробела перед закрывающей скобкой.

Объявление метода выглядит следующим образом. Обратите внимание на расположение скобок, запятых, пробелов, и фигурных скобок:

Объявление функции выглядит следующим образом. Обратите внимание на расположение скобок, запятых, пробелов и фигурных скобок:

4.5 Аргументы метода и функции

В списке аргументов НЕ ДОЛЖНО быть пробела перед каждой запятой, и ДОЛЖЕН быть один пробел после каждой запятой.

Аргументы метода и функции со значениями по умолчанию ДОЛЖНЫ помещаться в конец списка аргументов.

Списки аргументов МОГУТ быть разбиты на несколько строк, где каждая последующая строка имеет один отступ. При этом первый элемент в списке ДОЛЖЕН быть на следующей строке, и в каждой строке ДОЛЖЕН быть только один аргумент.

Когда список аргументов разбит на несколько строк, закрывающая скобка и открывающая фигурная скобка ДОЛЖНЫ быть помещены вместе на отдельной строке с одним пробелом между ними.

Когда у вас есть объявление возвращаемого типа, ДОЛЖЕН быть один пробел после двоеточия, за которым следует объявление типа. Двоеточие и объявление ДОЛЖНЫ быть в одной строке с закрывающей скобкой списка аргументов без пробелов между двумя символами.

В объявлениях типа Nullable НЕ ДОЛЖНО быть пробела между знаком вопроса и типом.

При использовании оператора ссылки & перед аргументом, НЕ ДОЛЖНО быть пробела после него, как в предыдущем примере.

НЕ ДОЛЖНО быть пробела между оператором троеточия и именем аргумента:

При комбинировании оператора ссылки и оператора троеточия variadic, между ними не должно быть пространства:

4.6 abstract, final и static

Если они присутствуют, abstract и final объявления ДОЛЖНЫ предшествовать объявлению видимости.

Когда присутствует объявление static, оно ДОЛЖНО быть после объявления видимости.

4.7 Вызовы методов и функций

При выполнении вызова метода или функции НЕ ДОЛЖНО быть пробела между именем метода или функции и открывающей скобкой. НЕ ДОЛЖНО быть пробела после открывающей скобки, и НЕ ДОЛЖНО быть пробела перед закрывающей скобкой. В списке аргументов НЕ ДОЛЖНО быть пробела перед каждой запятой, и ДОЛЖЕН быть один пробел после каждой запятой.

Списки аргументов МОГУТ быть разбиты на несколько строк, где каждая последующая строка имеет один отступ. При этом первый элемент в списке ДОЛЖЕН быть на следующей строке, и в каждой строке ДОЛЖЕН быть только один аргумент. Один аргумент, разбитый на несколько строк (как это может быть в случае с анонимной функцией или массивом), не представляет собой разбиение списка аргументов.

5. Контрольные структуры

Общие правила стиля для контрольных структур следующие:

  • ДОЛЖЕН быть один пробел после ключевого слова контрольной структуры
  • НЕ ДОЛЖНО быть пробела после открывающей скобки
  • НЕ ДОЛЖНО быть пробел перед закрывающей скобкой
  • ДОЛЖЕН быть один пробел между закрывающей скобкой и открывающей скобкой
  • Тело структуры ДОЛЖНО быть после отступа
  • Тело ДОЛЖНО быть на следующей строке после открывающей скобки
  • Закрывающая скобка ДОЛЖНА быть на следующей строке после тела

Тело каждой структуры ДОЛЖНО быть заключено в фигурные скобки. Это стандартизирует внешний вид структур и снижает вероятность появления ошибок при добавлении новых строк в тело.

5.1 if, elseif, else

Структура if выглядит следующим образом. Обратите внимание на расположение скобок, пробелов и фигурных скобок; и что else и elseif находятся на той же строке, что и закрывающая скобка из предыдущего тела.

Ключевое слово elseif ДОЛЖНО использоваться вместо else, если все контрольные ключевые слова выглядят как отдельные слова.

Выражения в скобках МОГУТ разбиваться на несколько строк, где между каждой последующей строкой имеется минимум один отступ. При этом первое условие ДОЛЖНО быть на следующей строке. Закрывающая скобка и открывающая фигурная скобка ДОЛЖНЫ быть размещены вместе на отдельной строке с одним пробелом между ними. Логические операторы между условиями всегда ДОЛЖНЫ быть в начале или в конце строки, а не в обоих местах.

5.2 switch, case

Структура switch выглядит следующим образом. Обратите внимание на расположение скобок, пробелов и фигурных скобок. Оператор case ДОЛЖЕН отделяться от switch одним отступом, а ключевое слово break (или другие завершающие ключевые слова) ДОЛЖНО иметь отступ на том же уровне, что и тело case. ДОЛЖЕН быть комментарий, такой как // no break, когда fall-through является преднамеренным в непустом теле case.

Выражения в скобках МОГУТ разбиваться на несколько строк, где между каждой последующей строкой имеется минимум один отступ. При этом первое условие ДОЛЖНО быть на следующей строке. Закрывающая скобка и открывающая фигурная скобка ДОЛЖНЫ быть размещены вместе на отдельной строке с одним пробелом между ними. Логические операторы между условиями всегда ДОЛЖНЫ быть в начале или в конце строки, а не в обоих местах.

5.3 while, do while

Оператор while выглядит следующим образом. Обратите внимание на расположение скобок, пробелов, и фигурных скобок.

Выражения в скобках МОГУТ разбиваться на несколько строк, где между каждой последующей строкой имеется минимум один отступ. При этом первое условие ДОЛЖНО быть на следующей строке. Закрывающая скобка и открывающая фигурная скобка ДОЛЖНЫ быть размещены вместе на отдельной строке с одним пробелом между ними. Логические операторы между условиями всегда ДОЛЖНЫ быть в начале или в конце строки, а не в обоих местах.

Аналогично, оператор do while выглядит следующим образом. Обратите внимание на расположение скобок, пробелов, и фигурных скобок.

Выражения в скобках МОГУТ разбиваться на несколько строк, где между каждой последующей строкой имеется минимум один отступ. При этом первое условие ДОЛЖНО быть на следующей строке. Логические операторы между условиями всегда ДОЛЖНЫ быть в начале или в конце строки, а не в обоих местах.

5.4 for

Формулировка for выглядит следующим образом. Обратите внимание на расположение скобок, пробелов, и фигурных скобок.

Выражения в скобках МОГУТ разбиваться на несколько строк, где между каждой последующей строкой имеется минимум один отступ. При этом первое условие ДОЛЖНО быть на следующей строке. Закрывающая скобка и открывающая фигурная скобка ДОЛЖНЫ быть размещены вместе на отдельной строке с одним пробелом между ними.

5.5 foreach

Оператор foreach выглядит следующим образом. Обратите внимание на расположение скобок, пробелов, и фигурных скобок.

5.6 try, catch, finally

Блок try-catch-finally выглядит следующим образом. Обратите внимание на расположение скобок, пробелов, и фигурных скобок.

6. Операторы

Правила стилей для операторов сгруппированы по арности (количество операндов, которые они принимают).

Когда пространство разрешено вокруг оператора, МОЖНО использовать несколько пробелов для удобства чтения.

Все операторы, не описанные здесь, остаются неопределенными.

6.1. Унарные операторы

Операторы инкремента/декремента НЕ ДОЛЖНЫ иметь пробел между оператором и операндом.

Операторы приведения типов НЕ ДОЛЖНЫ иметь пробела в скобках:

6.2. Бинарные операторы

Все бинарные арифметические, сравнительные, присваивающие, побитовые, логические, строковые, и типовые операторам ДОЛЖНЫ начинаться и заканчиваться пробелом:

6.3. Тернарные (условные) операторы

Условный оператору ДОЛЖЕН начинаться и заканчиваться пробелом вокруг обоих ? и : символов:

Когда средний операнд условного оператора исключен, оператор ДОЛЖЕН следовать тем же правилам стиля, что и другие бинарные операторы сравнения:

$variable = $foo ?: ‘bar’;

7. Замыкания

Замыкания ДОЛЖНЫ быть объявлены с пробелом после ключевого слова function и пробелом до и после ключевого слова use.

Открывающая скобка ДОЛЖНА находиться на той же строке, а закрывающая скобка ДОЛЖНА переходить на следующую строку, следующую за телом.

НЕ ДОЛЖНО быть пробела после открывающей скобки списка аргументов или списка переменных, и НЕ ДОЛЖНО быть пробела перед закрывающей скобкой списка аргументов или списка переменных.

В списке аргументов и списке переменных НЕ ДОЛЖНО быть пробела перед каждой запятой, и ДОЛЖЕН быть один пробел после каждой запятой.

Аргументы замыкания со значениями по умолчанию ДОЛЖНЫ помещаться в конец списка аргументов.

Если возвращаемый тип присутствует, он ДОЛЖЕН следовать тем же правилам, что и обычные функции и методы; если используется ключевое слово use, двоеточие ДОЛЖНО следовать за закрывающими скобками списка использования без пробелов между двумя символами.

Объявление замыкания выглядит следующим образом. Обратите внимание на расположение скобок, запятых, пробелов, и фигурных скобок:

Списки аргументов и списки переменных МОГУТ разбиваться на несколько строк, где каждая последующая строка имеет один отступ. При этом первый элемент в списке ДОЛЖЕН находиться на следующей строке, и в каждой строке ДОЛЖЕН быть только один аргумент или переменная.

Когда конечный список (будь то аргументы или переменные) разделен на несколько строк, закрывающая скобка и открывающая скобка ДОЛЖНЫ находиться на отдельной строке с одним пробелом между ними.

Ниже приведены примеры замыканий со списками аргументов и без них, а также списков переменных, разделенных на несколько строк.

Обратите внимание, что правила форматирования также применяются, когда замыкание используется непосредственно в вызове функции или метода в качестве аргумента.

8. Анонимные классы

Анонимные классы ДОЛЖНЫ следовать тем же рекомендациям и принципам, что и закрытие в вышеприведенном разделе.

Открывающая фигурная скобка МОЖЕТ быть в той же строке, что и ключевое слово class, если список интерфейсов реализует ее. Если список implements переносится, фигурная скобка ДОЛЖНА быть помещена в строке, следующей непосредственно за последним интерфейсом.

top top