wordpress-plus-php

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

Держите в голове следующие рекомендации, когда пишете PHP код для WordPress, будь-то код для ядра, плагинов, или тем. Указания во многих отношениях аналогичны стандартам PHP кода PEAR, но отличаются в некоторых ключевых моментах.

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

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

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

Отступы

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

Исключение: если у вас есть блок кода, который будет более читаемым, если содержимое будет выровнено, то используйте пробелы:

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

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

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

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

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

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

Обратите внимание, что требование использования фигурных скобках просто означает, что одиночные конструкции в стиле одной строки для управляющих структур — запрещены. Вы можете использовать альтернативный синтаксис для управляющих структур (например, if / endif, while / endwhile ) — особенно в шаблонах, где PHP код встраивается в HTML, например:

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

Perl совместимые регулярные выражения (PCRE, preg_ функции) должны быть использованы в предпочтении перед их POSIX коллегами. Никогда не используйте /e переключатель, используйте preg_replace_callback вместо этого.

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

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

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

Правильно:

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

Удаляйте завершающие пробелы

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

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

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

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

При определении функции, делайте следующим образом:

При вызове функции, так:

При выполнении логических сравнений, так:

При привидении типа, так:

При обращении к элементам массива, добавляйте пробел вокруг индекса, только если это переменная, например:

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

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

Функциям, которые обновляют базу данных следует ожидать передачу их параметров без SQL экранирования. Экранирование должно быть сделано как можно ближе к моменту запроса, насколько это возможно, предпочтительно с использованием $wpdb->prepare()

$wpdb->prepare() — метод, который управляет экранированием, кавычками и использованием чисел для запросов SQL. Он использует стиль форматирования в виде подмножества sprintf(). Пример:

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

См. раздел валидации данных в Кодексе для более подробной информации.

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

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

Если Вы должны коснуться базы данных, свяжитесь с некоторыми разработчиками, разместив сообщение в wp-hackers mailing list. Они могут рассмотреть вопрос о создании функции для следующей версии WordPress, чтобы покрыть функциональность, которую вы бы хотели.

Соглашения по присваиванию имен

Используйте строчные буквы в переменных, экшенах и именах функций (никогда CamelCase). Разделяйте отдельные слова через подчеркивания. Не сокращайте имена переменных без необходимости; пусть код будет однозначным и само-документирующимся.

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

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

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

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. , точка после слова class вместо дефиса.

Файлы, содержащие теги шаблонов в wp-includes должны иметь -template добавленный к концу имени, для очевидности.

general-template.php

Понятные значения флагов для аргументов функций

Предпочтительны строковые значения, чем просто TRUE или FALSE при вызове функций.

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

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

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

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

Йода условия

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

В приведенном выше примере, если вы пропустите знак равенства (признаться, это происходит даже с самыми опытными из нас), вы получите ошибку разбора, потому что вы не можете назначить присваивание такой константе, как TRUE. Если бы конструкция была обратной — ( $the_force = TRUE ) , присваивание будет прекрасно работать, возвращая 1, в результате чего, if-конструкция будет всегда TRUE, и вы могли бы долго гоняться за этой ошибкой.

Это немного странно для чтения. Используйте этот вариант и вы привыкните.

Это относится и к == , != , === и !==. Йода условия для <, >, <= или >= значительно труднее читать и лучше их избегать.

Умный Код

В общем случае, читаемость является более важной, чем одаренность или краткость.

Хотя линия выше талантливая, разобраться в ней займет некоторое время, если вы не знакомы с подобным. Поэтому, просто напишите, как здесь:

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

Как отмечается в PHP документации:

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

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

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

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

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

Джозеф Скотт сделал хорошую рецензию почему это плохо (I Don’t Like PHP’s extract() Function).

По материалам документации: WordPress > Make WordPress Core > Best Practices > PHP Coding Standards