WordPress как на ладони
Плагин рекламы для WordPress wordpress jino

Стандарты PHP кода в WordPress — лучшие практики

Чтобы код WordPress везде был в одном стиле и удобно читался в ядре, плагинах и темах, рекомендуется соблюдать стандарты написания кода, которые приняты разработчиками WordPress. Эти стандарты очень похожи на стандарт PEAR, однако есть и кардинальные отличия. Рекомендую ознакомится с ними и при создании плагинов или тем, по возможности, их соблюдать.

Кроме стандартов к написанию самого кода PHP, также есть стандарты документирования кода - это комментарии к функциям и хукам: PHP Documentation Standards (англ.)

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

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

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

Вторая строка в этом примере не очищает выводимые переменные, а это необходимо делать в целях безопасности. Поэтому для такой записи, переменные должны быть очищены заранее. В целом, такую запись можно считать неприемлемой! См. раздел учебника безопасный вывод.

к началу

Отступы

Отступ должен всегда показывать логическую структуру кода. Используйте табуляцию (клавиша Tab), а не пробелы - это дает больше гибкости. Пробелы стоит использовать, когда нужно выравнять что-либо внутри строки.

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

if ( условие ) {
[tab]$foo     = 'somevalue';
[tab]$foo2    = 'somevalue2';
[tab]$foo_bar = 'somevalue3';
[tab]$foo5    = 'somevalue4';
}

Для ассоциативных массивов, значения должны начинаться с новой строки. Рекомендуется ставить «последнюю» запятую при перечислении элементов массива - так удобнее добавлять новые элементы...

$my_array = array(
[tab]'foo'   => 'somevalue',
[tab]'foo2'  => 'somevalue2',
[tab]'foo3'  => 'somevalue3',
[tab]'foo34' => 'somevalue3',
);
к началу

Стиль фигурных скобок

Фигурные скобки должны использоваться для всех блоков в стиле, как показано ниже:

if ( условие ) {
	action1();
	action2();
} elseif ( условие2 && условие3 ) {
	action3();
	action4();
} else {
	defaultaction();
}

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

Следует комментировать любой код, который интуитивно не понятен.

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

if ( условие ) {
	action0();
}

if ( условие ) {
	action1();
} elseif ( условие2 ) {
	action2a();
	action2b();
}

foreach ( $items as $item ) {
	process_item( $item );
}

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

Можно использовать альтернативный синтаксис для управляющих структур: 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; ?>
к началу

Регулярные выражения

Используйте функции preg_* и не используйте функции ereg_* для регулярных выражений.

Используйте строки в одинарных кавычках для регулярных выражений, так как, в отличие от двойных кавычек, у них есть только два символа, который нужно экранировать: \' и \\.

Не используйте короткие PHP теги

Важно: Никогда не используйте короткие PHP теги.

Правильно:

<?php ... ?>
<?php echo $var; ?>

Не правильно:

<? ... ?>
<?= $var ?>

Удаляйте пробелы на конце строк

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

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

Так писать не следует:

<?php
$foo = 'строка';пробел
?>

Конец файла

Нужно так:

<?php
$foo = 'строка';

Конец файла

Использование пробела

Всегда ставьте пробелы после запятых, и на обеих сторонах логических операторов (! && ||), операторов сравнения (==), конкатенации (.) и операторов присваивания (.=).

x == 23
foo && bar
! foo
array( 1, 2, 3 )
$baz . '-5'
$term .= 'X'

Ставьте пробелы на обеих сторонах открывающих и закрывающих круглых скобок для блоков if, elseif, foreach, switch.

if ( $foo ) { ...

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 запроса, если запрос сложный, его можно разбить на несколько строк и добавить где нужно отступы. Хотя большинство конструкций пишутся в одну строку. Всегда пишите прописными такие части SQL конструкций, как: UPDATE, WHERE, FROM, JOIN.

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

$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() сам экранирует строки и добавляет кавычки, если надо. Преимущество prepare() в том, что не нужно помнить о ручном использовании esc_sql(), а также, что строка запроса с плейсхолдерами более наглядна, чем если бы там использовались переменные обернутые в esc_sql().

Смотрите описание метода $wpdb->prepare().

к началу

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

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

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

Имена классов, функций, файлов, констант, переменных

Имена функций, переменных, хуков

Используйте строчные буквы a-z в переменных, хуках и названиях функций и никогда 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

Этот стандарт именования файлов справедлив для всех существующих и новых файлов с классами. Однако существуют файлы исключения: class.wp-dependencies.php, class.wp-scripts.php, class.wp-styles.php. Эти файлы имеют префикс class., точка после слова class вместо дефиса.

В ядре, в папке wp-includes есть подключаемые файлы, в которых находятся функции, которые обычно используются в темах (в шаблоне). Файлы с такими функциями - тегами шаблона заканчиваются на -template.

к началу

Понятные значения переменных в параметрах функций

Булевам, предпочтительны строковые значения. Т.е. вместо true/false при вызове функций лучше использовать какую-то объясняющую значение параметра строку.

Плохой код:

function eat( $what, $slowly = true ) {
	...
}
eat( 'mushrooms' );
eat( 'mushrooms', true ); // что означает true?
eat( 'dogfood', false );  // что означает false, противоположность true?

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

Хороший код:

function eat( $what, $speed = 'slowly' ) {
	...
}
eat( 'mushrooms' );
eat( 'mushrooms', 'slowly' );
eat( 'dogfood', 'quickly' );

Когда нужно больше параметров функции, используйте массив $args. Он даже лучше!

Очень хороший код:

function eat( $what, $args ) {
	...
}
eat( 'noodles', array( 'speed' => 'moderate' ) );
к началу

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

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

Как нужно проверять:

// (если условие выполняется = true) ? (то делаем это) : (иначе это);
$music_type = ( 'jazz' == $music ) ? 'cool' : 'blah';
// (если значение не пустое - ! empty ) ? (то делаем это) : (иначе это);

Как не следует писать:

// (если условие не выполняется != true) ? (то делаем это) : (иначе это);
$music_type = ( 'jazz' != $music ) ? 'blah' : 'cool';
к началу

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

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

if ( true == $the_force ) {
	$victorious = you_will( $be );
}

Если пропустить второй знак = в приведенном примере (признаться, это происходит даже с самыми опытными из нас), то мы получим ошибку PHP и сразу её увидим, потому что код не будет работать. А вот если бы конструкция была обратной - $the_force = true, то условие всегда будет выполняться и никакой ошибки мы не увидим, и можем пропустить такой серьезный баг, который к тому же иногда сложно отловить!

К такому «перевернутому» написанию просто нужно привыкнуть.

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

к началу

Умный код

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

isset( $var ) || $var = some_function();

Да - это крутая запись, видно что сделал её опытный программист. Но любому другому разработчику, а зачастую даже и автору, для того чтобы разобраться в такой записи нужно немного вникать и потратить лишние секунды или минуты - это не очевидная и не понятная запись и её нужно избегать, и лучше её записать длиннее, но понятнее:

if ( ! isset( $var ) ) {
	$var = some_function();
}

Да, три строки, вместо одной, но это лучше...

к началу

Оператор подавления ошибок @

Из PHP документации:

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

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

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

к началу

Не используйте функцию extract()

По мотивам тикета #22400. extract() это ужасная функция, которая сильно усложняет отладку кода, также сильно усложняет читаемость и понимание кода. Поэтому никогда не используйте extract(), кроме случаев когда без неё не обойтись, т.е. никогда!

Почему extract() такая ужасная, хорошо объясняет Джозеф Скотт (англ.): I Don’t Like PHP’s extract() Function.

-

Статья подготовлена по материалам документации: PHP Coding Standards

Eugene Kopich 100web2033.com
Creative sites for creative people ★ Digital marketing
Стандарты PHP кода в WordPress - лучшие практики 2 комментария

Здравствуйте, !

Ваш комментарий