PSR-2: Руководство по стилю кодирования

Устаревший - по состоянию на 10 августа 2019 года PSR-2 помечен как устаревший. В качестве альтернативы теперь рекомендуется PSR-12 .

Это руководство расширяет и дополняет PSR-1 , базовый стандарт кодирования.

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

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

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

1. Обзор

Код ДОЛЖЕН соответствовать «руководству по стилю кодирования» PSR [ PSR-1 ].
Код ДОЛЖЕН использовать 4 пробела для отступов, а не табуляции.
НЕ ДОЛЖНО быть жесткого ограничения на длину строки; мягкий предел ДОЛЖЕН быть 120 символов; строки ДОЛЖНЫ состоять из 80 символов или меньше.
После namespace объявления ДОЛЖНА быть одна пустая строка, и после блока use объявлений ДОЛЖНА быть одна пустая строка .
Открывающие фигурные скобки для классов ДОЛЖНЫ располагаться на следующей строке, а закрывающие фигурные скобки ДОЛЖНЫ располагаться на следующей строке после тела.
Открывающие фигурные скобки для методов ДОЛЖНЫ располагаться на следующей строке, а закрывающие фигурные скобки ДОЛЖНЫ располагаться на следующей строке после тела.
Видимость ДОЛЖНА быть объявлена для всех свойств и методов; abstract и final ДОЛЖЕН быть объявлен до видимости; static ДОЛЖЕН быть объявлен после видимости.
Ключевые слова структуры управления ДОЛЖНЫ иметь один пробел после них; вызовы методов и функций НЕ ДОЛЖНЫ.
Открывающие фигурные скобки для управляющих структур ДОЛЖНЫ располагаться на одной строке, а закрывающие фигурные скобки ДОЛЖНЫ располагаться на следующей строке после тела.
Открывающие круглые скобки для управляющих структур НЕ ДОЛЖНЫ иметь пробел после них, а закрывающие круглые скобки для управляющих структур НЕ ДОЛЖНЫ иметь пробел перед.

1.1. Пример

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

<?php
namespace Vendor\Package;

use FooInterface;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

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

    final public static function bar()
    {
        // method body
    }
}

2. Общие

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

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

2.2. Файлы

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

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

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

2.3. Линии

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

Мягкое ограничение на длину строки ДОЛЖНО составлять 120 символов; автоматические средства проверки стиля ДОЛЖНЫ предупреждать, но НЕ ДОЛЖНЫ ошибаться на мягком пределе.

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

НЕ ДОЛЖНЫ быть завершающие пробелы в конце непустых строк.

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

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

2.4. Отступ

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

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

2.5. Ключевые слова и True / False / Null

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

Константы PHP true, falseи null должны быть в нижнем регистре.

3. Пространство имен и объявления использования

Если он присутствует, после namespace объявления ДОЛЖНА быть одна пустая строка .

Если они присутствуют, все use объявления ДОЛЖНЫ идти после namespace объявления.

В объявлении ДОЛЖНО быть одно use ключевое слово.

После use блока ДОЛЖНА быть одна пустая строка .

Например:

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

// ... additional PHP code ...

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

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

4.1. Расширяет и реализует

extends И implements ключевые слова должны быть объявлены на одной и той же строке, что и имя класса.

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

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class ClassName extends ParentClass implements \ArrayAccess, \Countable
{
    // constants, properties, methods
}

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

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class ClassName extends ParentClass implements
    \ArrayAccess,
    \Countable,
    \Serializable
{
    // constants, properties, methods
}

4.2. Характеристики

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

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

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

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

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

<?php
namespace Vendor\Package;

class ClassName
{
    public $foo = null;
}

4.3. Методы

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

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

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

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

<?php
namespace Vendor\Package;

class ClassName
{
    public function fooBarBaz($arg1, &$arg2, $arg3 = [])
    {
        // method body
    }
}

4.4. Аргументы метода

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

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

<?php
namespace Vendor\Package;

class ClassName
{
    public function foo($arg1, &$arg2, $arg3 = [])
    {
        // method body
    }
}

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

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

<?php
namespace Vendor\Package;

class ClassName
{
    public function aVeryLongMethodName(
        ClassTypeHint $arg1,
        &$arg2,
        array $arg3 = []
    ) {
        // method body
    }
}

4.5. `abstract`, `final`И`static`

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

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

<?php
namespace Vendor\Package;

abstract class ClassName
{
    protected static $foo;

    abstract protected function zim();

    final public static function bar()
    {
        // method body
    }
}

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

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

<?php
bar();
$foo->bar($arg1);
Foo::bar($arg2, $arg3);

<?php
$foo->bar(
    $longArgument,
    $longerArgument,
    $muchLongerArgument
);

5. Структуры управления

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

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

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

5.1. `if`, `elseif`,`else`

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

<?php
if ($expr1) {
    // if body
} elseif ($expr2) {
    // elseif body
} else {
    // else body;
}

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

5.2. `switch`,`case`

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

<?php
switch ($expr) {
    case 0:
        echo 'First case, with a break';
        break;
    case 1:
        echo 'Second case, which falls through';
        // no break
    case 2:
    case 3:
    case 4:
        echo 'Third case, return instead of break';
        return;
    default:
        echo 'Default case';
        break;
}

5.3. `while`,`do while`

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

<?php
while ($expr) {
    // structure body
}

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

<?php
do {
    // structure body;
} while ($expr);

5.4. `for`

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

<?php
for ($i = 0; $i < 10; $i++) {
    // for body
}

5.5. `foreach`

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

<?php
foreach ($iterable as $key => $value) {
    // foreach body
}

5.6. `try`,`catch`

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

<?php
try {
    // try body
} catch (FirstExceptionType $e) {
    // catch body
} catch (OtherExceptionType $e) {
    // catch body
}

6. Закрытие

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

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

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

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

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

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

<?php
$closureWithArgs = function ($arg1, $arg2) {
    // body
};

$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
    // body
};

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

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

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

<?php
$longArgs_noVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) {
    // body
};

$noArgs_longVars = function () use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
    // body
};

$longArgs_longVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
    // body
};

$longArgs_shortVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) use ($var1) {
    // body
};

$shortArgs_longVars = function ($arg) use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
    // body
};

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

<?php
$foo->bar(
    $arg1,
    function ($arg2) use ($var1) {
        // body
    },
    $arg3
);

7. Заключение

В этом руководстве намеренно опущены многие элементы стиля и практики. К ним относятся, но не ограничиваются:

Объявление глобальных переменных и глобальных констант
Объявление функций
Операторы и назначение
Межстрочное выравнивание
Блоки комментариев и документации
Префиксы и суффиксы имени класса
Лучшие практики

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