Структура некоторых частей кода WordPress непоследовательна с точки зрения разметки и стиля. WordPress работает над постепенным улучшением кода, помогая пользователям поддерживать единый стиль, так чтобы код мог стать чистым и легко читающимся.
Имейте в виду следующие моменты при написании PHP-кода для WordPress, будь то основной код программы, плагины или темы. Руководящие принципы во многих отношениях похожи на стандарты Pear, но отличаются в некоторых ключевых аспектах.
См. также: PHP Documentation Standards.
Используйте одинарные и двойные кавычки, когда это необходимо. Если вы не оцениваете ничего в строке, используйте одинарные кавычки. Почти никогда не следует избегать кавычек в строке, потому что вы можете просто чередовать тип кавычек, например, так:
echo '<a href="/static/link" title="Yeah yeah!">Link name</a>'; echo "<a href='$link' title='$linktitle'>$linkname</a>";
Текст, который входит в атрибуты, должен обрабатываться esc_attr(), чтобы одинарные или двойные кавычки не заканчивали значение атрибута, не вызывали проблем с HTML-валидацией и не вызывали проблем безопасности. Для дальнейших подробностей см. Data Validation в Кодексе.
Отступы должны всегда отражать логическую структуру. Используйте настоящие табуляции, а не пробелы, так как это обеспечивает наибольшую гибкость для клиентов.
Исключение: если у вас есть блок кода, который будет более читабельным при выравнивании, используйте пробелы:
[tab]$foo = 'somevalue'; [tab]$foo2 = 'somevalue2'; [tab]$foo34 = 'somevalue3'; [tab]$foo5 = 'somevalue4';
Для ассоциативных массивов значения должны начинаться с новой строки. Обратите внимание на запятую после последнего элемента массива: это рекомендуется, поскольку так легче менять порядок элементов в массиве и добавлять новые элементы.
$my_array = array( [tab]'foo' => 'somevalue', [tab]'foo2' => 'somevalue2', [tab]'foo3' => 'somevalue3', [tab]'foo34' => 'somevalue3', );
Эмпирическое правило: табуляции должны использоваться в начале строки для формирования отступа, в то время как пробелы могут использоваться в середине строки для выравнивания.
Фигурные скобки используются для всех блоков в стиле, показанном здесь:
if ( condition ) {
action1();
action2();
} elseif ( condition2 && condition3 ) {
action3();
action4();
} else {
defaultaction();
}
Кроме того, если у вас есть действительно длинный блок, рассмотрите возможность его разбиения на два или больше коротких блоков или функций. Если вы считаете, что присутствие такого длинного блока неизбежно, поместите, пожалуйста, краткий комментарий в конце, чтобы люди могли быстро определить окончание блока - обычно это правило подходит для блоков длиннее приблизительно 35 строк, но любой код, который не является интуитивно понятным, может быть прокомментирован.
Фигурные скобки должны использоваться всегда, даже когда они не являются обязательными:
if ( condition ) {
action0();
}
if ( condition ) {
action1();
} elseif ( condition2 ) {
action2a();
action2b();
}
foreach ( $items as $item ) {
process_item( $item );
}
Обратите внимание, что требование использования скобок просто означает, что запрещены управляющие inline-конструкции, состоящие из одной инструкции. Вы можете свободно использовать альтернативный синтаксис для управляющих конструкций (например, if/endif, while/endwhile) - особенно в ваших шаблонах, где PHP-код встраивается в HTML, например:
<?php if ( have_posts() ) : ?>
<div class="hfeed">
<?php while ( have_posts() ) : the_post(); ?>
<article id="post-<?php the_ID() ?>" class="<?php post_class() ?>">
<!-- ... -->
</article>
<?php endwhile; ?>
</div>
<?php endif; ?>
Perl-совместимым регулярным выражениям (PCRE, preg_ функции) должно отдаваться предпочтение по сравнению с их POSIX-аналогами. Никогда не используйте переключатель /e, используйте вместо этого preg_replace_callback.
Наиболее удобно использовать для регулярных выражений одиночные кавычки, поскольку в отличие от строк в двойных кавычках, у них есть только две управляющие последовательности: \' и \\.
Важно: никогда не используйте сокращенные открывающие PHP-теги.
Правильно:
<?php ... ?>
Неправильно:
<? ... ?>
Удаляйте конечные пробелы в конце каждой строки кода. Желательно опускать закрывающий PHP-тег в конце файла. Если вы его все же используете, убедитесь, что вы удалите лишние пробелы в конце файла.
Всегда ставьте пробелы после запятых и по обе стороны логических операторов, сравнений, строк и операторов присваивания.
x == 23 foo && bar ! foo array( 1, 2, 3 ) $baz . '-5' $term .= 'X'
Ставьте пробелы по обе стороны открывающих и закрывающих скобок блоков if, elseif, foreach, for, switch.
foreach ( $foo as $bar ) { ...
Определение функции:
function my_function( $param1 = 'foo', $param2 = 'bar' ) { ...
Вызов функции:
my_function( $param1, func_param( $param2 ) );
Выполнение логических сравнений:
if ( ! $foo ) { ...
foreach ( (array) $foo as $bar ) { ...
$foo = (boolean) $bar;
При обращении к элементам массива ставьте пробелы вокруг индекса только если он является переменной, например:
$x = $foo['bar']; // правильно $x = $foo[ 'bar' ]; // неправильно $x = $foo[0]; // правильно $x = $foo[ 0 ]; // неправильно $x = $foo[ $bar ]; // правильно $x = $foo[$bar]; // неправильно
При форматировании SQL-предложений вы можете разбивать их на несколько строк и использовать отступы, если они достаточно сложные. Хотя большинство предложений хорошо работают и в виде одной строки. Всегда используйте прописные буквы для SQL-частей предложений, таких как UPDATE или WHERE.
В функции, которые обновляют базу данных, параметры должны передаваться после экранирования спецсимволов. Экранирование должно быть сделано как можно ближе к запросу, предпочтительно с помощью $wpdb->prepare().
$wpdb->prepare() - это метод, который управляет экранированием спецсимволов, заключением строк в кавычки и фильтрацией целочисленных параметров для SQL-запросов. Он использует подмножество стиля форматирования sprintf(). Пример :
$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() будет заботиться об экранировании спецсимволов и заключении строк в кавычки за нас. Преимущество этого заключается в том, что мы не должны беспокоиться о ручном использовании esc_sql(), и в том, что с первого взгляда видно, выполнено экранирование или нет, потому что оно делается непосредственно перед запросом.
См. Data Validation в Кодексе для более подробной информации.
Не делайте запросов к базе данных напрямую. Если есть функции, которые могут получить нужные вам данные, используйте их. Абстрагирование от базы данных (использование функций вместо запросов) помогает сохранить совместимость вашего кода в будущем; и в случаях, когда результаты кэшируются в памяти, это может быть во много раз быстрее.
Если вам все же необходимо обратиться напрямую к базе данных, свяжитесь с разработчиками, отправив сообщение в список рассылки wp-hackers. Возможно они захотят рассмотреть возможность создания функции для следующей версии WordPress, содержащей нужную вам функциональность.
Используйте строчные буквы в именах переменных, действий и функций (никогда не используйте camelCase-нотацию). Разделяйте слова с помощью знака подчеркивания. Не сокращайте имена переменных без необходимости; пусть код будет понятным и самодокументированным.
function some_name( $some_variable ) { [...] }
Имена классов должны образовываться из слов, начинающихся с прописной буквы и разделенных символами подчеркивания. Все сокращения должны быть в верхнем регистре.
class Walker_Category extends Walker { [...] }
class WP_HTTP { [...] }
Имена констант должны быть в верхнем регистре со знаками подчеркиваниями, разделяющими слова:
define( 'DOING_AJAX', true );
Имена файлов должны описывать содержание и состоять из строчных букв. Слова должны разделяться дефисами.
my-plugin-name.php
Имена файлов, содержащих классы, должны образовываться на основе имени класса с префиксом class-, знаки подчеркивания в имени класса должны заменяться на дефисы, например WP_Error становится:
class-wp-error.php
Эти стандарты именования файлов распространяются на все имеющиеся и новые файлы с классами. Исключение составляют три файла, которые содержат код, входящий в BackPress: class.wp-dependencies.php, class.wp-scripts.php, class.wp-styles.php. Эти файлы начинаются с префикса class., содержащего точку, а не дефис.
Файлы, содержащие теги шаблонов в wp-includes должны иметь -template в конце имени, чтобы их содержание было очевидно.
general-template.php
При вызове функций отдавайте предпочтение строковым значениям, а не просто true и false.
// Неправильно
function eat( $what, $slowly = true ) {
...
}
eat( 'mushrooms' );
eat( 'mushrooms', true ); // Что значит true?
eat( 'dogfood', false ); // Что значит false?
Поскольку PHP не поддерживает именованные аргументы, значения флагов не имеют смысла, и каждый раз, когда мы сталкиваемся с вызовом функции, подобным приведенному выше, мы должны искать определение функции. Код можно сделать более читаемым, заменив логические значения осмысленными строковыми.
// Правильно
function eat( $what, $speed = 'slowly' ) {
...
}
eat( 'mushrooms' );
eat( 'mushrooms', 'slowly' );
eat( 'dogfood', 'quickly' );
Тернарные операторы - это хорошо, но всегда проверяйте истинность утверждения, а не ложность. В противном случае, они становятся запутанными. (Исключением может быть использование ! empty(), поскольку проверка на ложь здесь более понятна.)
Например:
// (if statement is true) ? (do this) : (else, do this); $musictype = ( 'jazz' == $music ) ? 'cool' : 'blah'; // (if field is not empty ) ? (do this) : (else, do this);
if ( true == $the_force ) {
$victorious = you_will( $be );
}
При выполнении логических сравнений всегда ставьте переменную справа, а константы и литералы слева.
В приведенном выше примере, если вы пропустите один знак равенства (это случается даже с самыми опытными из нас), вы получите синтаксическую ошибку, потому что вы не можете присвоить значение константе true. Если бы условие было записано наоборот ( $the_force = true ), присваивание было бы вполне допустимым, возвращало бы 1, и условие бы оценивалось как true, и вы могли бы долго искать ошибку.
Такую запись немного странно читать. Но делайте так и вы привыкнете.
Это относится к ==, !=, ===, !==. Условия Йоды для <, >, <=, >= читать значительно труднее, поэтому их лучше избегать.
В целом, читабельность важнее ума или краткости.
isset( $var ) || $var = some_function();
Хотя приведенная выше линия кода - умная, требуется время, чтобы ее понять, если вы не сталкивались с этим раньше. Поэтому лучше написать так:
if ( ! isset( $var ) ) {
$var = some_function();
}
Как отмечается в PHP docs:
PHP поддерживает один оператор управления ошибками: знак @. Когда он предшествует какому-либо PHP-выражению, любое сообщение об ошибке, которое может быть сгенерировано данным выражением, будет проигнорировано.
Поскольку этот оператор существует в ядре, он часто используется вместо того, чтобы делать надлежащие проверки на ошибки. Его использование крайне не рекомендуется, поскольку PHP docs также утверждает:
Предупреждение: в настоящее время оператор управления ошибками "@" отключает даже сообщения о критических ошибках, которые приводят к прекращению работы скрипта. Среди прочего, это означает, что если вы будете использовать "@" для подавления ошибок, возникающих при работе какой-либо функции, является ли она недоступной или содержит опечатку, скрипт прекратит работу без указания причины.