Расширение спецификации кода Psr-12

Автор оригинала: David Wong.

Статья была переслана из профессионального сообщества разработчиков laravel. Оригинальная ссылка: https://learnku.com/laravel/t

Ключевые слова в статье ДОЛЖНЫ , НЕ ДОЛЖНЫ , ТРЕБУЮТСЯ , ДОЛЖНЫ , НЕ ДОЛЖНЫ , НЕ ДОЛЖНЫ , РЕКОМЕНДУЕТСЯ , МОЖЕТ и НЕОБЯЗАТЕЛЬНО Все объяснено в [RFC 2119] [].

абстрактный

Эта спецификация наследует, расширяет и заменяет [psr-2] [], а стиль кодирования соответствует базовому стандарту кодирования [psr-1] []. Как и [psr-2] [], цель этой спецификации-уменьшить когнитивный конфликт, когда разные люди читают код. В нем перечислены способы форматирования PHP Общие правила и ожидания кодекса для достижения этой цели. PSR Попробуйте предоставить набор методов, можно использовать инструменты стиля кодирования, проекты могут соответствовать, разработчики могут легко использовать в разных проектах. Когда разработчики работают над несколькими проектами, это может помочь обеспечить общий набор рекомендаций в этих проектах. Поэтому ценность этого руководства заключается не в самих правилах, а в том, чтобы делиться этими правилами.

[psr-2] [] был принят в 2012 году, а затем PHP Было много изменений, которые повлияли на стиль кодирования. И [psr-2] – это PHP Широко используются основные функции кодирования. Поэтому PSR Пытается объяснить это более современным способом PSR-2 Содержание и новые функции и PSR-2 Внести исправления.

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

На протяжении всего документа любые инструкции могут быть проигнорированы, если они не существуют в версии PHP, поддерживаемой вашим проектом.

например

Этот пример содержит следующие правила в качестве краткого обзора:

php

declare(strict_types=1);

namespace Vendor\Package;

use Vendor\Package\{ClassA as A, ClassB, ClassC as C};
use Vendor\Package\SomeNamespace\ClassD as D;

use function Vendor\Package\{functionA, functionB, functionC};

use const Vendor\Package\{ConstantA, ConstantB, ConstantC};

class Foo extends Bar implements FooInterface
{
    public function sampleFunction(int $a, int $b = null): array
    {
        if ($a === $b) {
            bar();
        } elseif ($a > $b) {
            $foo->bar($arg1);
        } else {
            BazClass::bar($arg2, $arg3);
        }
    }

    final public static function bar()
    {
        //Method content
    }
}

2. общие положения

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

Код должен соответствовать всем правилам, перечисленным в [psr-1].

Термин “studlycaps” в psr-1 следует интерпретировать как регистр Паскаля, где первая буква каждого слова пишется с заглавной буквы, включая первую букву.

2.2 документ

Все PHP-файлы могут заканчиваться только на UNIX LF (разрыв строки).

Все файлы PHP должны заканчиваться непустой строкой и буквой LF.

В файлах, содержащих только PHP-код, вы должны опустить знак окончания ?> .

2.3 кодовые строки

Не должно быть жестких ограничений на длину строки.

Мягкий предел длины строки должен составлять 120 символов.

Длина строки не должна превышать 80 символов; строка, превышающая эту длину, должна быть разделена на несколько последующих строк, и длина каждой строки не должна превышать 80 символов.

В окончаниях строк не может быть конечных пробелов.

Вы можете добавлять пустые строки для улучшения читабельности и указывать связанные блоки кода, если это явно не запрещено.

У вас не может быть более одного оператора на строку.

2.4 отступ

Код должен содержать отступ с 4 пробелами для каждого уровня отступа, и метки отступов нельзя использовать.

2.5 ключевые слова и типы

Все ключевые слова и типы PHP [[1]] Ключевые слова] [типы] Должны Использовать нижний регистр.

Все новые ключевые слова и типы в будущих версиях PHP также Должны Использовать строчные буквы.

Введите ключ Должен Использовать сокращения. Используйте bool Вместо логическое Используйте int Вместо целое число Подождите.

3. Объявление, пространство имен и импорт

Заголовок PHP-файла может содержать несколько блоков. Если блоков несколько, каждый блок В основном Разделен пустыми строками и другими блоками, а внутри блока Не может Содержать пустые строки. Все блоки Должны В следующем порядке, если блок не существует, он игнорируется.

Начальный тег PHP-файла: 。
。
Блок документов на уровне файлов.
Одно или несколько заявлений о декларации.
Оператор объявления пространства имен. Оператор объявления на основе одного или нескольких классов use
. Один или несколько методов, основанных на использовании
Заявлении об объявлении. Один или несколько операторов объявления на основе констант use
.

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

когда это начинается? Тег находится в первой строке файла, он должен находиться в отдельной строке, и других инструкций нет, если только это не тег открытия и закрытия файла, содержащий теги, отличные от PHP.

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

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

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

И следующее не допускается:

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

Например:

Оператор объявления не может содержать пробелов и должен быть полностью declare(strict_types=1) (с необязательным терминатором точки с запятой).

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

declare(ticks=1) {
    //Some codes
}

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

“Класс” здесь относится ко всем классам, интерфейсам и признакам.

Любые комментарии и утверждения Не должны Содержать одну и ту же строку после ее правой фигурной скобки.

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

new Foo();

4.1 наследование и реализация

Ключевое слово наследовать и Реализация Должны Объявляться в той же строке, что и имя класса.

Левая фигурная скобка для класса Должна Другая строка; правая фигурная скобка Должна Следовать за следующей строкой тела класса.

Левая фигурная скобка для класса Должна Ходить одна и Не должна В предыдущей или следующей строке есть пустые строки.

Правая скобка Должна Ходить одна, и Не должна Над ней есть пустая строка.

Если есть интерфейс, Реализация Интерфейс и наследование Родительский класс Конечно Он разделен на несколько строк. В первом нужно сделать отступ один раз. При этом первый интерфейс Должен Записываться в следующей строке, и в каждой строке Должен Может быть записан только один интерфейс.

4.2 использование признака

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

Трассировка для каждого импортированного класса Должна Каждая строка содержит объявление, и каждая содержит объявление Должна Свой собственный использовать Оператор импорта.

В файле класса, если после использования “использовать торговлю” больше ничего нет, закрывающая скобка для имени класса должна начинаться с другой строки.

Если есть что-то еще, пожалуйста, оставьте пустую строку между ними.

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

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

Все атрибуты Должны Видимость объявления.

Если минимальная версия PHP вашего проекта поддерживает постоянную видимость (PHP 7.1 или выше), все константы Должны Объявлять видимость.

Ключевое слово var Не должно Использоваться для объявления свойств.

Каждый оператор Не должен Объявлять более одного свойства.

Имя атрибута Не должно начинаться с одного подчеркивания, чтобы указать его защищенную или закрытую видимость. То есть подчеркивание в начале явно бессмысленно.

Между объявлением типа и именем свойства Должно Есть пробел.

Декларация свойств выглядит следующим образом:

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

Все методы Должны Тип объявлен заранее.

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

В именах методов и функций после имен методов Не должно. Используйте пробелы. Фигурные скобки в начале метода Должны Писать в строке после объявления метода и закрывать фигурные скобки Должны Писать в строке после метода. После открывающей скобки и перед закрывающей скобкой не должно быть пробелов.

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

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

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

В списке параметров Не должно Перед каждой запятой есть пробел, и Должно После каждой запятой есть пробел.

Параметры со значениями по умолчанию в методах и функциях Должны В конце списка параметров.

список параметров Конечно Он разделен на несколько строк, и параметры каждой строки имеют отступ один раз. При этом первый параметр Должен В следующей строке, и в каждой строке Должен Может быть только один параметр.

Когда список параметров разделен на несколько строк, правая скобка и левая фигурная скобка Должны Располагаться в одной строке и выстраиваться отдельно, с пробелом между ними.

При определении объявления типа возвращаемого значения объявление типа после двоеточия Должно разделяться пробелом. Двоеточия и операторы Должны Между одной и той же строкой и закрывающей скобкой после списка параметров нет пробела.

В объявлении типа, допускающего значение null, между знаком вопроса и объявлением типа Не может Есть пробелы.

Когда оператор ссылки используется перед параметром & После оператора ссылки Не может , существуют пробелы, как в примере выше.

Между тремя точками объявления параметра переменной и именем параметра не может быть пробелов:

public function process(string $algorithm, ...$parts)
{
    // function body
}

При использовании операторов как ссылочных, так и переменных параметров Не может Любые пробелы:

public function process(string $algorithm, &...$parts)
{
    // function body
}

4.6 абстрактные, окончательные и статические

Если это абстрактный и окончательный , то оператор должен быть оператором видимости.

Если это статический , объявление должно следовать за объявлением видимости.

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

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

bar($arg1);
Foo::bar($arg2, $arg3);

Список параметров можно разделить на несколько строк, причем в каждой строке один раз делается отступ. После этого первая строка в списке должна находиться в следующей строке, и каждая строка должна иметь только один параметр. Разделение одного параметра на несколько строк (например, анонимные функции или массивы) не составляет сам список параметров разделения.

bar(
    $longArgument,
    $longerArgument,
    $muchLongerArgument
);

get('/hello/{name}', function ($name) use ($app) {
    return 'Hello ' . $app->escape($name);
});

5. Управление технологическим процессом

Ниже приведены основные правила стиля управления процессом:

После ключевых слов управления процессом Должно Должно быть место
После левой скобки Не может Пробел
Перед правой скобкой Не может Пробел
Между правой скобкой и левой скобкой Должно Должно быть пространство
Основной корпус процесса Должен Сделать отступ один раз
Основная часть процесса Должна Начинать другую строку после левой скобки
Правые скобки Должны Другая строка после тела процесса

Каждый объект управления процессом Должен Закрываться закрытыми скобками. Это стандартизирует структуру процесса, одновременно снижая вероятность возникновения ошибок из-за добавления в процесс нового контента.

5.1 если, в противном случае, иначе

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

Ключевое слово elseif Должно заменить иначе, если Таким образом, ключевые слова управления выглядят как слово.

Выражения в круглых скобках Вероятно Будут разделены на несколько строк, каждая строка будет иметь отступ не менее одного раза. Если это так, то первое условие Должно В новой строке. Правая скобка и левая скобка Должны Находиться на одной линии, с пробелом посередине. Логический контроллер в середине условия Должен В начале или конце каждой строки, а не смешивать.

5.2 выключатель, корпус

переключатель Структура выглядит следующим образом. Обратите внимание на положение круглых скобок, пробелов и фигурных скобок. случай |/Должен Отступ один раз от переключателя Сначала прервать Ключевые слова (или другие ключевые слова завершения) Должен Сумма отступов уход Основная часть последовательна. Должен Иметь изображение //без завершения Такой комментарий не пустой и продолжается уход В теме.

Выражения в круглых скобках Вероятно Будут разделены на несколько строк, в каждой строке по крайней мере один раз будет сделан отступ. Если это так, то первое условие Должно В новой строке. Правая скобка и левая скобка Должны Находиться на одной линии, с пробелом посередине. Логический контроллер в середине условия Должен В начале или в конце строки нет, а не смешивание.

5.3 пока, делайте, пока

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

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

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

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

5.4 для

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

5.5 для каждого

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

 $value) {
    //Iteration body
}

5.6 попробуйте , поймайте , наконец

Один попробуй-поймай-наконец-то Модуль содержит следующее. Обратите внимание на его круглые скобки, пробелы и фигурные скобки.

6. оператор

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

Если вокруг операторов разрешены пробелы, Обязательно Введите несколько пробелов для удобства чтения.

Все операторы, не описанные здесь, временно не ограничены.

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

Между операторами приращения/уменьшения и операндами Не должно Быть пробелов.

$i++;
++$j;

Внутри круглых скобок операторов преобразования типов Не должно Любые пробелы:

$intValue = (int) $input;

6.2. Двоичный оператор

Всем двоичным арифметическим операторам, операторам сравнения, присваивания, побитовым, логическим, строковым и типовым операторам должен предшествовать по крайней мере один пробел:

if ($a === $b) {
    $foo = $bar ?? $a ?? $b;
} elseif ($a > $b) {
    $foo = $a + $b * $c;
}

6.3. Троичный оператор

Условные операторы, также известные как тернарные операторы, должны быть ? и : Между этими двумя символами:

$variable = $foo ? 'foo' : 'bar';

Если вы опускаете средний операнд условного оператора, оператор должен следовать тем же правилам стиля, что и другие операторы двоичного сравнения:

$variable = $foo ?: 'bar';

7. Закрытие

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

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

Пробелы не могут быть помещены после и перед открывающими и закрывающими скобками параметров и переменных.

Вы не можете ставить пробелы перед запятыми для параметров и переменных, но вы должны поставить 1 пробел после запятых.

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

Если объявлен тип возвращаемого значения, он должен следовать тем же правилам, что и обычные функции и методы; если использовать Ключевые слова, двоеточия должны быть в использовать Пробелы не допускаются после закрывающих скобок и до и после двоеточий.

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

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

При завершении многострочного списка (или параметра, переменной) закройте скобку и откройте скобку Необходимо Поместить ее в одну строку с пробелом посередине.

Ниже приведен пример закрытия со списком многострочных параметров и переменных и без него.

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

bar(
    $arg1,
    function ($arg2) use ($var1) {
        // body
    },
    $arg3
);

8. анонимная категория

Анонимный класс Должен Следовать тем же рекомендациям и рекомендациям, что и в предыдущем разделе.

до тех пор, пока реализует Список интерфейсов не обернется, левая фигурная скобка Конечно И ключевые слова класс В одной строке. Если список интерфейсов закрывается, фигурные скобки Должны В следующей строке последнего интерфейса.