PSR-12: Перевод расширенного стандарта оформления кода

Декабрь 10, 2019

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

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

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

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

PSR-2 был принят в 2012 году, и с тех пор в PHP был внесен ряд изменений, которые повлияли на рекомендации по стилю кодирования. В то время как PSR-2 является довольно полным набором функционала PHP, который существовал на момент написания, новый функционал можно интерпретировать по-разному. Таким образом, этот PSR стремится прояснить содержание 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 body
  }
}

<?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 body

}

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

/**
 * This file contains an example of coding styles.
 */

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 Vendor\Package\AnotherNamespace\ClassE as E;

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

use const Vendor\Package\{CONSTANT_A, CONSTANT_B, CONSTANT_C};
use const Another\Vendor\CONSTANT_D;

/**
 * FooBar is an example class.
 */
class FooBar
{
    // ... additional PHP code ...
}

<?php

/**

* This file contains an example of coding styles.

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 Vendor\Package\AnotherNamespace\ClassE as E;

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

use function Another\Vendor\functionD;

use const Vendor\Package\{CONSTANT_A, CONSTANT_B, CONSTANT_C};

use const Another\Vendor\CONSTANT_D;

/**

* FooBar is an example class.

class FooBar

{

// ... additional PHP code ...

}

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


<?php

use Vendor\Package\SomeNamespace\{
    SubnamespaceOne\ClassA,
    SubnamespaceOne\ClassB,
    SubnamespaceTwo\ClassY,
    ClassZ,
};

<?php

use Vendor\Package\SomeNamespace\{

SubnamespaceOne\ClassA,

SubnamespaceOne\ClassB,

SubnamespaceTwo\ClassY,

ClassZ,

};

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


<?php

use Vendor\Package\SomeNamespace\{
    SubnamespaceOne\AnotherNamespace\ClassA,
    SubnamespaceOne\ClassB,
    ClassZ,
};

<?php

use Vendor\Package\SomeNamespace\{

SubnamespaceOne\AnotherNamespace\ClassA,

SubnamespaceOne\ClassB,

ClassZ,

};

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

Например:


<?php declare(strict_types=1) ?>
<html>
<body>
    <?php
        // ... additional PHP code ...
    ?>
</body>
</html>

<?php declare(strict_types=1) ?>

<html>

<body>

<?php

// ... additional PHP code ...

</body>

</html>

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

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


declare(ticks=1) {
    // some code
}

declare(ticks=1) {

// some code

}

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

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

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

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


new Foo();

new Foo();

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

НЕОБХОДИМО, чтобы ключевые слова 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
}

<?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 и, в случае интерфейсов, extends МОГУТ быть разбиты на несколько строк, где каждая последующая строка имеет один отступ. При этом первый элемент в списке ДОЛЖЕН быть на следующей строке, и ДОЛЖЕН быть только один интерфейс на строку.


<?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
}

<?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 Использование трейтов (traits)

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


<?php

namespace Vendor\Package;

use Vendor\Package\FirstTrait;

class ClassName
{
    use FirstTrait;
}

<?php

namespace Vendor\Package;

use Vendor\Package\FirstTrait;

class ClassName

{

use FirstTrait;

}

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


<?php

namespace Vendor\Package;

use Vendor\Package\FirstTrait;
use Vendor\Package\SecondTrait;
use Vendor\Package\ThirdTrait;

class ClassName
{
    use FirstTrait;
    use SecondTrait;
    use ThirdTrait;
}

<?php

namespace Vendor\Package;

use Vendor\Package\FirstTrait;

use Vendor\Package\SecondTrait;

use Vendor\Package\ThirdTrait;

class ClassName

{

use FirstTrait;

use SecondTrait;

use ThirdTrait;

}

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


<?php

namespace Vendor\Package;

use Vendor\Package\FirstTrait;

class ClassName
{
    use FirstTrait;
}

<?php

namespace Vendor\Package;

use Vendor\Package\FirstTrait;

class ClassName

{

use FirstTrait;

}

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


<?php

namespace Vendor\Package;

use Vendor\Package\FirstTrait;

class ClassName
{
    use FirstTrait;

    private $property;
}

<?php

namespace Vendor\Package;

use Vendor\Package\FirstTrait;

class ClassName

{

use FirstTrait;

private $property;

}

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


<?php

class Talker
{
    use A, B, C {
        B::smallTalk insteadof A;
        A::bigTalk insteadof C;
        C::mediumTalk as FooBar;
    }
}

<?php

class Talker

{

use A, B, C {

B::smallTalk insteadof A;

A::bigTalk insteadof C;

C::mediumTalk as FooBar;

}

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

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

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

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

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

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

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

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


<?php

namespace Vendor\Package;

class ClassName
{
    public $foo = null;
    public static int $bar = 0;
}

<?php

namespace Vendor\Package;

class ClassName

{

public $foo = null;

public static int $bar = 0;

}

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

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

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

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

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


<?php

namespace Vendor\Package;

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

<?php

namespace Vendor\Package;

class ClassName

{

public function fooBarBaz($arg1, &$arg2, $arg3 = [])

{

// method body

}

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


<?php

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

<?php

function fooBarBaz($arg1, &$arg2, $arg3 = [])

{

// function body

}

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

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

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


<?php

namespace Vendor\Package;

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

<?php

namespace Vendor\Package;

class ClassName

{

public function foo(int $arg1, &$arg2, $arg3 = [])

{

// method body

}

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


<?php

namespace Vendor\Package;

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

<?php

namespace Vendor\Package;

class ClassName

{

public function aVeryLongMethodName(

ClassTypeHint $arg1,

&$arg2,

array $arg3 = []

) {

// method body

}

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


<?php

declare(strict_types=1);

namespace Vendor\Package;

class ReturnTypeVariations
{
    public function functionName(int $arg1, $arg2): string
    {
        return 'foo';
    }

    public function anotherFunction(
        string $foo,
        string $bar,
        int $baz
    ): string {
        return 'foo';
    }
}

<?php

declare(strict_types=1);

namespace Vendor\Package;

class ReturnTypeVariations

{

public function functionName(int $arg1, $arg2): string

{

return 'foo';

}

public function anotherFunction(

string $foo,

string $bar,

int $baz

): string {

return 'foo';

}

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


<?php

declare(strict_types=1);

namespace Vendor\Package;

class ReturnTypeVariations
{
    public function functionName(?string $arg1, ?int &$arg2): ?string
    {
        return 'foo';
    }
}

<?php

declare(strict_types=1);

namespace Vendor\Package;

class ReturnTypeVariations

{

public function functionName(?string $arg1, ?int &$arg2): ?string

{

return 'foo';

}

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

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


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

public function process(string $algorithm, ...$parts)

{

// processing

}

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


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

public function process(string $algorithm, &...$parts)

{

// processing

}

4.6 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
    }
}

<?php

namespace Vendor\Package;

abstract class ClassName

{

protected static $foo;

abstract protected function zim();

final public static function bar()

{

// method body

}

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

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


<?php

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

<?php

bar();

$foo->bar($arg1);

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

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


<?php

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

<?php

$foo->bar(

$longArgument,

$longerArgument,

$muchLongerArgument

);


<?php

somefunction($foo, $bar, [
  // ...
], $baz);

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

<?php

somefunction($foo, $bar, [

// ...

], $baz);

$app->get('/hello/{name}', function ($name) use ($app) {

return 'Hello ' . $app->escape($name);

});

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

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

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

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

5.1 if, elseif, else

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


<?php

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

<?php

if ($expr1) {

// if body

} elseif ($expr2) {

// elseif body

} else {

// else body;

}

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

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


<?php

if (
    $expr1
    && $expr2
) {
    // if body
} elseif (
    $expr3
    && $expr4
) {
    // elseif body
}

<?php

if (

$expr1

&& $expr2

) {

// if body

} elseif (

$expr3

&& $expr4

) {

// elseif body

}

5.2 switch, case

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

<?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;

}


<?php

switch (
    $expr1
    && $expr2
) {
    // structure body
}

<?php

switch (

$expr1

&& $expr2

) {

// structure body

}

5.3 while, do while

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


<?php

while ($expr) {
    // structure body
}

<?php

while ($expr) {

// structure body

}


<?php

while (
    $expr1
    && $expr2
) {
    // structure body
}

<?php

while (

$expr1

&& $expr2

) {

// structure body

}

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


<?php

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

<?php

do {

// structure body;

} while ($expr);


<?php

do {
    // structure body;
} while (
    $expr1
    && $expr2
);

<?php

do {

// structure body;

} while (

$expr1

&& $expr2

);

5.4 for

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


<?php

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

<?php

for ($i = 0; $i < 10; $i++) {

// for body

}


<?php

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

<?php

for (

$i = 0;

$i < 10;

$i++

) {

// for body

}

5.5 foreach

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


<?php

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

<?php

foreach ($iterable as $key => $value) {

// foreach body

}

5.6 try, catch, finally

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


<?php

try {
    // try body
} catch (FirstThrowableType $e) {
    // catch body
} catch (OtherThrowableType | AnotherThrowableType $e) {
    // catch body
} finally {
    // finally body
}

<?php

try {

// try body

} catch (FirstThrowableType $e) {

// catch body

} catch (OtherThrowableType | AnotherThrowableType $e) {

// catch body

} finally {

// finally body

}

6. Операторы

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

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

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

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

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


$i++;
++$j;

$i++;

++$j;

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


$intValue = (int) $input;

$intValue = (int) $input;

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

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


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

if ($a === $b) {

$foo = $bar ?? $a ?? $b;

} elseif ($a > $b) {

$foo = $a + $b * $c;

}

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

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


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

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

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

$variable = $foo ?: ‘bar’;

7. Замыкания

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

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

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

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

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

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

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


<?php

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

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

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

<?php

$closureWithArgs = function ($arg1, $arg2) {

// body

};

$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {

// body

};

$closureWithArgsVarsAndReturn = function ($arg1, $arg2) use ($var1, $var2): bool {

// 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

$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
);

<?php

$foo->bar(

$arg1,

function ($arg2) use ($var1) {

// body

$arg3

);

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

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


<?php

$instance = new class {};

<?php

$instance = new class {};

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


<?php

// Brace on the same line
$instance = new class extends \Foo implements \HandleableInterface {
    // Class content
};

// Brace on the next line
$instance = new class extends \Foo implements
    \ArrayAccess,
    \Countable,
    \Serializable
{
    // Class content
};

<?php

// Brace on the same line

$instance = new class extends \Foo implements \HandleableInterface {

// Class content

};

// Brace on the next line

$instance = new class extends \Foo implements

\ArrayAccess,

\Countable,

\Serializable

{

// Class content

};