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

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


freelanceland
Лучшие исполнители для ваших задач

Устаревший - по состоянию на 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 truefalseи 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. abstractfinalИ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. ifelseif,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. Заключение

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

  • Объявление глобальных переменных и глобальных констант

  • Объявление функций

  • Операторы и назначение

  • Межстрочное выравнивание

  • Блоки комментариев и документации

  • Префиксы и суффиксы имени класса

  • Лучшие практики

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

Популярное

PSR-3: Интерфейс логирования
PSR-7: интерфейсы сообщений HTTP
PSR-1: базовый стандарт кодирования

Возврат к списку