Обрамление PHP-кода

PHP-код должен всегда обрамляться полными PHP-тегами:

<?php
 
?>

Короткие теги не допустимы. В файлах, содержащих только PHP-код, закрывающий так должен быть опущен. (Смотри Общие стандарты).

Строки

Строковые литералы

Когда строка является литеральной (не содержит подстановок переменных), для ее обрамления должны использоваться апострофы или "одинарные кавычки":

$a = 'Example String';

Строковые литералы, содержащие апострофы

Когда строка литералов сама содержит апострофы, разрешается для обрамления строки использовать "двойные кавычки". Это особенно актуально для SQL-запросов:

$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";

Синтаксис выше является более предпочтительным, чем экранирование апострофов.

Подстановка переменных

Подстановка переменных разрешается с использованием нижеприведенных форм:

$greeting = "Hello $name, welcome back!";
 
$greeting = "Hello {$name}, welcome back!";

Для надежности, эта форма не допустима:

$greeting = "Hello ${name}, welcome back!";

Конкатенация строк

Строки должны объединятся с помощью оператора ".". Пробел должен всегда добавляться до и после оператора "." для улучшения читабельности:

$company = 'Zend' . ' ' . 'Technologies';

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

$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";

Массивы

Массивы с числовыми индексами

Отрицательные числа в качестве индексов запрещены.

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

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

$sampleArray = array(1, 2, 3, 'Zend', 'Studio');

Также разрешается определять многострочные индексированные массивы, используя конструкцию "array". В этом случае, каждая следующая строка должна быть дополнена пробелами так, чтобы начало каждой строки было выравнено как показано ниже:

$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500);

В качестве альтернативы, начальный элемент может располагаться на следующей строке. В этом случае он должен быть сдвинут на один уровень отступа больше, чем строка содержащая объявление массива. Все последующие строки должны иметь аналогичный отступ. Закрывающая скобка должна быть на отдельной строке с уровнем отступа, что и строка, содержащая объявление массива:

$sampleArray = array(
    1, 2, 3, 'Zend', 'Studio',
    $a, $b, $c,
    56.44, $d, 500,
);

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

Ассоциативные массивы

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

$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');

В качестве альтернативы, начальный элемент может располагаться на следующей строке. В этом случае он должен быть сдвинут на один уровень отступа больше, чем строка содержащая объявление массива. Все последующие строки должны иметь аналогичный отступ. Закрывающая скобка должна быть на отдельной строке с уровнем отступа, что и строка, содержащая объявление массива. Для удобочитаемости, "=>" должен быть выравнен пробелами относительно остальных:

$sampleArray = array(
    'firstKey'  => 'firstValue',
    'secondKey' => 'secondValue',
);

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

Классы

Определение класса

Классы должны быть именованы согласно схеме именования Zend Framework.

Фигурная скобка всегда пишется на следующей строке под именем класса.

Каждый класс должен иметь блок документации (doc-блок) в соответствии со стандартом PHPDocumentor.

Код внутри класса должен иметь отступ в четыре пробела.

Только один класс разрешен внутри одного PHP-файла.

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

Это пример допустимого определения класса:

/**
 * Doc-блок здесь
 */
class SampleClass
{
    // содержимое класса должно быть
    // с отступом в четыре пробела
}

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

class SampleClass extends FooAbstract implements BarInterface
{
}

Если в результате такого объявления, длина строки превышает максимальную длину строки, сделайте перенос перед ключевыми словами "extends" и/или "implements" и сделайте отступ в один уровень.

class SampleClass
    extends FooAbstract
    implements BarInterface
{
}

Если класс реализует несколько интерфейсов и объявление превышает максимальную длину строки - сделайте перенос после запятой, разделяющей интерфейсы, и выровняйте их имена пробелами:

class SampleClass
    implements BarInterface,
               BazInterface
{
}

Переменные-члены классов

Переменные-члены классов должны быть именованы согласно схеме именования Zend Framework.

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

Ключевое слово var не разрешено. Члены класса должны всегда определять их область видимости, используя ключевое слово private, protected или public. К публичным переменным-членам класса доступ напрямую разрешен, но не приветствуется в пользу методов доступа (set & get).

Функции и методы

Определение функций и методов

Функции должны должны быть именованы согласно схеме именования Zend Framework.

Функции внутри классов должны всегда определять свою область видимости с помощью одного из префиксов private, protected или public.

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

Функции в глобальной области видимости крайне не приветствуются.

Это пример допустимого определения функции:

/**
 * Doc-блок здесь
 */
class Foo
{
    /**
     * Doc-блок здесь
     */
    public function bar()
    {
        // содержимое класса должно быть
        // с отступом в четыре пробела
    }
}

В случае, если список аргументов превышает максимальную длину строки, можно делать перенос строки. Аргументы, перенесенные на следующую строку, должны иметь отступ на один уровень больше чем у объявления метода или функции. Закрывающая скобка должна быть на новой строке с отступом, как у объявления функции/метода, а после нее, через пробел, должна находиться открывающая фигурная скобка. Ниже приведен пример такой ситуации:

/**
 * Doc-блок здесь
 */
class Foo
{
    /**
     * Doc-блок здесь
     */
    public function bar($arg1, $arg2, $arg3,
        $arg4, $arg5, $arg6
    ) {
        // содержимое класса должно быть
        // с отступом в четыре пробела
    }
}

Note: Передача по ссылке допустима только в определениях функций:

/**
 * Doc-блок здесь
 */
class Foo
{
    /**
     * Doc-блок здесь
     */
    public function bar(&$baz)
    {}
}

Передача по ссылке во время вызова строго запрещена.

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

/**
 * Doc-блок здесь
 */
class Foo
{
    /**
     * ПЛОХО
     */
    public function bar()
    {
        return($this->bar);
    }
 
    /**
     * ХОРОШО
     */
    public function bar()
    {
        return $this->bar;
    }
}

Использование функций и методов

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

threeArguments(1, 2, 3);

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

Для функций, чьи аргументы допускают массив, вызов функции может включать конструкцию "array" и может быть разделено на несколько строк для улучшения читабельности. В этом случае, применим стандарт описания массивов:

threeArguments(array(1, 2, 3), 2, 3);
 
threeArguments(array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500), 2, 3);
 
threeArguments(array(
    1, 2, 3, 'Zend', 'Studio',
    $a, $b, $c,
    56.44, $d, 500
), 2, 3);

Управляющие структуры

If / Else / Elseif

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

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

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

if ($a != 2) {
    $a = 2;
}

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

if (($a == $b)
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
}

Цель последнего формата - предотвратить сложности, при добавлении или удалении условий из условного выражения в последующих изменениях.

Для выражения "if", включающего "elseif" или "else", форматирование должно быть таким, как в следующем примере:

if ($a != 2) {
    $a = 2;
} else {
    $a = 7;
}
 
if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
    $a = 4;
} else {
    $a = 7;
}
 
if (($a == $b)
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
} elseif (($a != $b)
          || ($b != $c)
) {
    $a = $c;
} else {
    $a = $b;
}

PHP допускает написание таких выражений без фигурных скобок при некоторых условиях. Стандарт кодирования не делает различий - для всех "if", "elseif" или "else" выражений необходимо использовать фигурные скобки.

Switch

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

Все содержимое между фигурными скобками пишется с отступом в четыре пробела. Содержимое каждого "case" выражения должно писаться с отступом в дополнительные четыре пробела.

switch ($numPeople) {
    case 1:
        break;
 
    case 2:
        break;
 
    default:
        break;
}

Ключевое слово default никогда не должно опускаться в выражении switch.

Note: Иногда полезно писать case выражения, которые передают управление следующему case выражению, опуская break или return. Для того, чтобы отличать такие случаи от ошибок, каждое case выражение, где опущен break или return, должно содержать комментарий, указывающий, что это сделано преднамеренно.

Встроенная документация

Формат документации

Все блоки документации ("doc-блоки") должны быть совместимы с форматом phpDocumentor. Описание формата phpDocumentor вне рамок данного докумета. Для дополнительно информации смотрите: » http://phpdoc.org/

Все файлы с классами должны содержать doc-блок "уровня файла" и непосредственно перед каждым классом doc-блок "уровня класса". Примеры таких doc-блоков можно увидеть ниже.

Файлы

Каждый файл, содержащий PHP-код должен иметь заголовочный doc-блок в начале файла, содержащий как минимум следующие phpDocumentor-теги(для Zend Framework):

/**
* Краткое описание файла
 *
 * Длинное описание файла (если есть)
 *
 * LICENSE: информация относительно лицензии
 *
 * @category   Zend
 * @package    Zend_Magic
 * @subpackage Wand
 * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license   BSD License
 * @version    $Id:$
 * @link       http://framework.zend.com/package/PackageName
 * @since      File available since Release 1.5.0
*/

Тэг @category должен иметь значение "Zend".

Тэг @package должен быть, и иметь значение, соответствующее имени компонента, к которому принадлежит класс. Обычно, имеет только два сегмента: префикс "Zend" и имя компонента.

Тэг @subpackage необязателен. Если предоставлен, должен быть именем подкомпонента минус префикс класса. В примере выше, предполагается, что класс в файле или "Zend_Magic_Wand", или использует это имя в качестве части части префикса.

Классы

Каждый класс должен иметь doc-блок, содержащий как минимум следующие phpDocumentor-теги:

/**
 * Краткое описание класса
 *
 * Длинное описание класса (если есть)...
 *
 * @category   Zend
 * @package    Zend_Magic
 * @subpackage Wand
 * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license   BSD License
 * @version    Release: @package_version@
 * @link       http://framework.zend.com/package/PackageName
 * @since      Class available since Release 1.5.0
 * @deprecated Class deprecated in Release 2.0.0
 */

Тэг @category должен иметь значение "Zend".

Тэг @package должен быть, и иметь значение, соответствующее имени компонента, к которому принадлежит класс. Обычно, имеет только два сегмента: префикс "Zend" и имя компонента.

Тэг @subpackage необязателен. Если предоставлен, должен быть именем подкомпонента минус префикс класса. В примере выше, предполагается, что класс в файле или "Zend_Magic_Wand", или использует это имя в качестве части части префикса.

Функции

Каждая функция, включая методы объектов, должна иметь doc-блок, содержащий как минимум:

Описание функции
Все аргументы
Все возможные возвращаемые значения

Нет надобности использовать тег "@access", потому что область видимости уже известна из ключевых слов "public", "private" или "protected". используемых при определении функции.

Если функция/метод может выбрасывать исключение, используйте тег @throws:

@throws exceptionclass [описание]

Стиль кодирования

Обрамление PHP-кода

Строки

Строковые литералы

Строковые литералы, содержащие апострофы

Подстановка переменных

Конкатенация строк

Массивы

Массивы с числовыми индексами

Ассоциативные массивы

Классы

Определение класса

Переменные-члены классов

Функции и методы

Определение функций и методов

Использование функций и методов

Управляющие структуры

If / Else / Elseif

Switch

Встроенная документация

Формат документации

Файлы

Классы

Функции