Руководство написания кода

1. Обзор

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

  • НЕ ОБЯЗАТЕЛЬНЫ жесткие ограничения на длину строки; мягкое ограничение ОБЯЗАТЕЛЬНО должно быть равно 120 символам; строки ДОЛЖНЫ содержать 80 или меньше символов.

  • После объявления пространства_имен ДОЛЖНА быть одна пустая строка, также после объявления блока 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 sampleFunction($a, $b = null)
    {
        if ($a === $b) {
            bar();
        } elseif ($a > $b) {
            $foo->bar($arg1);
        } else {
            BazClass::bar($arg2, $arg3);
        }
    }

    final public static function bar()
    {
        // тело метода
    }
}

2. Общее

2.1 Основной стандарт написания кода

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

2.2 Файлы

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

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

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

2.3. Строки

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

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

Строкам НЕ СЛЕДУЕТ быть длинее 80 символов; строки длиннее СЛЕДУЕТ разделить на несколько последующих строк, не более 80 символов каждая.

В конце непустых строк НЕ ДОЛЖНО быть пустого пространства.

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

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

2.4. Отступы

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

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

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

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

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

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

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

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

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

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

Например:

<?php
namespace Vendor\Package;

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

// ... Дополнительный PHP код ...

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
{
    // константы, свойства, методы
}

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

<?php
namespace Vendor\Package;

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

class ClassName extends ParentClass implements
    \ArrayAccess,
    \Countable,
    \Serializable
{
    // константы, свойства, методы
}

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 = [])
    {
        // тело метода
    }
}

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

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

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

<?php
namespace Vendor\Package;

class ClassName
{
    public function foo($arg1, &$arg2, $arg3 = [])
    {
        // тело метода
    }
}

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

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

<?php
namespace Vendor\Package;

class ClassName
{
    public function aVeryLongMethodName(
        ClassTypeHint $arg1,
        &$arg2,
        array $arg3 = []
    ) {
        // тело метода
    }
}

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()
    {
        // тело метода
    }
}

4.6. Вызов Метода или Функции

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

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

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

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

5. Управляющие Структуры

Главные правила стиля для управляющих структур следующие:

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

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

5.1. ifelseifelse

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

<?php
if ($expr1) {
    // тело if
} elseif ($expr2) {
    // тело elseif
} else {
    // тело else;
}

Ключевое слово elseif СЛЕДУЕТ использовать вместо else if, так чтобы все ключевые слова выглядели как единое слово.

5.2. switchcase

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

5.3. whiledo while

Выражение while должно выглядеть, как показано ниже. Обратите внимание на расположение скобок и пробелов.

<?php
while ($expr) {
    // тело структуры
}

Кроме того, выражение do while должно выглядеть, как показано ниже. Обратите внимание на расположение скобок и пробелов.

<?php
do {
    // тело структуры;
} while ($expr);

5.4. for

Выражение for должно выглядеть, как показано ниже. Обратите внимание на расположение скобок и пробелов.

<?php
for ($i = 0; $i < 10; $i++) {
    // тело for.
}

5.5. foreach

Выражение foreach должно выглядеть, как показано ниже. Обратите внимание на расположение скобок и пробелов.

<?php
foreach ($iterable as $key => $value) {
    // тело foreach
}

5.6. trycatch

Блок try catch должен выглядеть, как показано ниже. Обратите внимание на расположение скобок и пробелов.

<?php
try {
    // тело try
} catch (FirstExceptionType $e) {
    // тело catch
} catch (OtherExceptionType $e) {
    // тело catch
}

6. Замыкания

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

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

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

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

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

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

<?php
$closureWithArgs = function ($arg1, $arg2) {
    // тело
};

$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
    // тело
};

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

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

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

<?php
$longArgs_noVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) {
   // тело
};

$noArgs_longVars = function () use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
   // тело
};

$longArgs_longVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
   // тело
};

$longArgs_shortVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) use ($var1) {
   // тело
};

$shortArgs_longVars = function ($arg) use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
   // тело
};

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

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

7. Вывод

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

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

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

  • Операторами и присваиванием.

  • Выравнивание

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

  • Преффиксы и суффиксы названий классов

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

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

Раздел: