Соглашение по именованию аналогично соглашению по именованию Zend Framework с некоторыми дополнениями.
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!";
Строки должны объединятся с помощью оператора ".". Пробел должен всегда добавляться до и после оператора "." для улучшения читабельности, при использовании echo допустимо не конкатенировать строки, а выводить через запятую:
$company = 'Med' . ' ' . 'About' . ' ' . 'Me';
Когда производится конкатенация строк с помощью оператора ".", разрешается разрывать выражение на несколько строк для улучшения читабельности. В этом случае, каждая следующая строка должна быть дополнена пробелами так, чтобы оператор "." был выровнен под оператором "=":
$sql = "SELECT id, name FROM people "
. "WHERE name = 'Susan' "
. "ORDER BY name ASC ";
Массивы необходимо задавать конструкцией [] вместо array(), кроме тех случаев, где это явно не рекомендуется:
- проект на PHP 5.3 и младше без возможности миграции на старшие версии;
- массив описывает параметры компонента Битрикс (также аналогичные места, связанные с парсером Bitrix). Актуально только для вызова компонентов, чьи настройки должны редактироваться через визуальный редактор.
Отрицательные числа в качестве индексов запрещены.
Хотя индекс массива может начинаться с любого неотрицательного числа, но не приветствуется и не рекомендуется начинать индексирование не с 0.
Когда определяется индексированный массив с помощью конструкции [], завершающий пробел должен быть добавлен после каждой запятой для улучшения читабельности:
$sampleArray = [1, 2, 3, 'Med', 'Me'];
Также разрешается определять многострочные индексированные массивы, используя конструкцию "[]". В этом случае, каждая следующая строка должна быть дополнена пробелами так, чтобы начало каждой строки было выравнено как показано ниже:
$sampleArray = array[
1,
2,
3,
'Med',
'About',
$a,
56.44,
$d
];
Когда определяется ассоциативный массив с помощью конструкции [], необходимо разделение выражения на несколько строк. В этом случае, каждая следующая строка должна быть дополнена с помощью пробелов так, чтобы и ключи и значения были выровнены, "=>" должен быть выравнен пробелами относительно остальных:
$sampleArray = [
'firstKey' => 'firstValue',
'secondKey' => 'secondValue'
];
- Классы должны быть именованы согласно схеме именования Zend Framework.
- Фигурная скобка всегда пишется на следующей строке под именем класса.
- Каждый класс должен иметь блок документации (doc-блок) в соответствии со стандартом PHPDocumentor.
- Код внутри класса должен иметь отступ в четыре пробела.
- Только один класс разрешен внутри одного 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(&$baz) {}
}
! Передача по ссылке во время вызова строго запрещена. ! Возвращаемое значение не должно обрамляться в круглые скобки, иначе это ухудшает читабельность, а также может нарушить код, если метод позже станет возвращать результат по ссылке.
- Аргументы функции разделяются одним завершающим пробелом после каждой запятой. Это пример допустимого вызова функции для функции, которая принимает три аргумента:
- threeArguments(1, 2, 3);
- Передача по ссылке во время вызова запрещена. Смотрите секцию определения функций для правильного способа передачи аргументов функции по ссылке.
- Для функций, чьи аргументы допускают массив, вызов функции может включать конструкцию "[]" и может быть разделено на несколько строк для улучшения читабельности. В этом случае применим стандарт описания массивов.
- Полный синтаксис (endif; endforeach;) СТРОГО ЗАПРЕЩЁН.
- Управляющие структуры, основанные на конструкциях if и elseif, должны иметь один пробел до открывающей круглой скобки условия, и один пробел после закрывающей круглой скобки.
- Внутри выражения условия между круглыми скобками операторы должны разделяться пробелами для читабельности. Внутренние скобки приветствуются для улучшения логической группировки больших условий.
- Открывающаяся фигурная скобка пишется на той же строке, что и условие. Закрывающаяся фигурная скобка пишется на отдельной строке. Все содержимое между скобками пишется с отступом в четыре пробела.
if ($a != 2) {
$a = 2;
}
- Для всех "if", "elseif" или "else" выражений необходимо использовать фигурные скобки.