Регламент по оформлению кода PHP

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

Совет к ознакомлению с литературой

Именование

1. Все названия для папок и файлов должны быть осмысленными и говорящими (не требующие дополнительного разъяснения).
2. Для именования используем англоязычные слова (не транслит, если иного не требуется).
3. Директории и файлы именуются в нижнем регистре с разделением слов символом (-).
4. Названия классов должны соответствовать PascalCase. В PascalCase каждое слово начинается с заглавной буквы.
5. Названия методов и переменных должны соответствовать camelCase.
6. Названия переменных должны соответствовать camelCase.
7. Не используйте отрицательные логические название: вместо isInvalid используем !isValid
8. Переменные, хранящие в себе множество значений, именуем во сножественном числе
9. Имена итераторов в циклах формируем от названия массива (прим. $products as $product)
10. Используйте одно и тоже название для переменных с одинаковым назначением

Общее оформление кода

Точки с запятой

Точку с запятой всегда ставим в конце строки, только если весь блок кода не состоит из одной строки

<?
$digit = 0;
$count = 0;
....
?>

<? $digit = 0 ?>

Теги PHP

Если блок кода состоит из 1 строки, то теги php располагаем на этой же строке, отделяем код от тегов одлиночными пробелами.

<? $digit = 0 ?>

Если блок кода многострочный, то выносим теги PHP на отдельные строки, а внутри пишем код. Код внутри тегов не выделяем табуляцией.

<?
$digit = 0;
$count = 0;
....
?>

Блоки с PHP кодом выделяются табуляцией на равне с находящимися рядом HTML тегами (вложеность показываем табуляцией).

Одинарные и двойные кавычки

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

echo '<a href="/static/link" title="Yeah yeah!">Link name</a>';

echo "<a href='$link' title='$linktitle'>$linkname</a>";
echo "<div>$title</div>";
echo "<div>{$title . $subtitle}</div>";

Отступы и выравнивание

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

function() {
    $digit;
}

Ассоциативные массивы всегда выравниваем по самой длинной строке

$highstack = [
    'key' => 'value',
    'key' => 'value',
    'key' => 'value',
];

Отступы от других языковых конструкций

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

<div></div>

    <? foreach($items as $item): ?>
        <div></div>
    <? endforeach ?>

<div></div>

Выравнивание кода

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

echo '<a href="/static/link" title="Yeah yeah!">Link name</a>';

echo "<a href='$link' title='$linktitle'>$linkname</a>";
echo "<div>$title</div>";
echo "<div>{$title . $subtitle}</div>";

Объединение кода в осмыследннфые фрагменты

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

Короткий Синтаксис Массива

Вместо объявления массивов с использованием синтаксиса array( 1, 2, 3 ) сокращаем до [ 1, 2, 3 ].

Убирайте мёртвый код

Код всегда должен быть актуальным, закомменченных участков быть не должно.

Условия

Не забываем при помощи условий проверять значения переменных на null или falseю

Тернарный оператор

Рекомендуется проверять правдивые утверждения (исключение - !empty()). Стоит избегать в ниих двойного отрицания

Базовый синкансис:

$a = $b ? $b : $c;

В данном случе оператор необходимо записывать в краткой форме

$a = $b ?: $c;

Условия Магистра Йоды

При выполнении логических сравнений, всегда ставьте константы или литералы - слева, а переменную - справа.

if ( true == $varible ) {
  ...
}

Такая запись позволяет сразу выявить баг, если разработчик пропустит второй знак =, тк php сразу выдаст ошибку.

Это относится и к == , != , === и !==. «Условия Йоды» для <, >, <= или >= значительно труднее читать и тут их лучше не использовать.

Сравнение

Для обычного сравнения используйте ’==’ и ’!==’ вместо ’=’ и ’!=’, если при сравнении не требуется игнорировать типы.

Оператор объединения с null

Зачастую, вместо isset() или тернарного оператора нужно использовать оператор объединения с null

Пример обычного кода:

if (isset($_GET['name'])) {
    $name = $_GET['name'];
} elseif (isset($_POST['name'])) {
    $name = $_POST['name'];
} else {
    $name = 'nobody';
}

Пример нового варианта кода:

$name = $_GET['name'] ?? $_POST['name'] ?? 'nobody';

Циклы

Вложенности

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

Функции, заменяющие привычный цикл

Для работы с массивами стараемся использовать array_reduce, array_walk, array_chunk, array_column, array_search, array_find и так далее.

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

Проверка на валидность

Мы всегда должны быть уверены, что передаваемы в цикл данные не окажутся null или false;

Функции

Разбиение функций

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

Не используйте флаги в качестве параметров функций

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

Указание типов данных

При объявлении функции обязательно указывать, какого типа аргументы принимает функция, и что она возвращает. Вместо

function combine($val1, $val2): int
{
    if (!is_numeric($val1) || !is_numeric($val2)) {
        throw new \Exception('Must be of type Number');
    }

    return $val1 + $val2;
}

делаем

function combine(int $val1, int $val2): int
{
    return $val1 + $val2;
}

Если функция ничего не возвращает, то необходимо указать есть :void.

Избегайте негативных условий

Не используем функции, проверяющие негативное условие, вместо этого функция должныпроверяыть положительный вариант и при условии его можно отрицать.

function isDOMNodePresent(\DOMNode $node): bool
{
    // ...
}

if (!isDOMNodePresent($node)) {
    // ...
}

Избегайте условных выражений

Если у вас фукнция содержит if, то это означает, что функция выполняет больше, чем что-то одно. По возможности необходимо этого избегать.

Анонимные функции

Анонимные функции полезны, когда нужно записать коротко цельную логическую конструкцию с использование PHP функции. Например, вызов preg_replace_callback() можно записать так:

$caption = preg_replace_callback(
  '/<[a-zA-Z0-9]+(?: [^<>]+>)*/',
  function ( $matches ) {
    return preg_replace( '/[\r\n\t]+/', ' ', $matches[0] );
  },
  $caption
);

Такой код улучшает читаемость.

Работа с базой данных

Форматирование SQL конструкций

При форматировании SQL запроса, если запрос сложный, его можно разбить на несколько строк и добавить где нужно отступы. Хотя большинство конструкций пишутся в одну строку. Всегда пишите прописными такие части SQL конструкций, как: UPDATE, WHERE, FROM, JOIN.

Очистка, экранирование запроса должна быть сделана как можно позднее. Для защиты запроса используем $wpdb->prepare().

$var = "dangerous'";      // необработанные данные, которые могут быть экранированы или не экранированы
$id  = some_foo_number(); // данные ожидаются как число, но мы не уверены

$wpdb->query( $wpdb->prepare( "UPDATE $wpdb->posts SET post_title = %s WHERE ID = %d", $var, $id ) );

%s используется для строк и %d для целых чисел. Обратите внимание, что они не ‘в кавычках’! $wpdb->prepare() сам экранирует строки и добавляет кавычки, если необходимо.

Запросы базы данных

Старайтесь не писать прямых запросов к базе данных. Если есть подходящая функция, а их в WP много, которая может получить необходимые данные - используйте ее.

Использование функций вместо запросов, помогает сохранить будущую совместимость кода. Кроме того многие функции работают с кэшем, а это может значительно ускорить работу кода.