WPCS — это набор PHP_CodeSniffer
правил (сниффов) для проверки кода, разработанного для WordPress. Он обеспечивает качество кода и соблюдение соглашений официальных стандартов кода для WordPress.
Если вы работаете в команде и/или хотите писать более качественный код, то стоит подумать о едином стандарте кодирования (coding standard). Даже если вы в своей команде смогли договорится о каком-то стандарте, то очень сложно его придерживаться без инструментов контроля. Инструменты для контроля качества стандарта кодирования называются линтеры, которые существуют для каждого языка программирования.
Линтер – утилита для проверки код на соответствие стандартам и спецификациям языка. К примеру, для Python он существует в виде пакета Pylint, для PHP — PHP CodeSniffer, для JavaScript – ESHint, для Java – FindBugs и т.д.
Wikipedi
WordPress Coding Standard включает в себя не только пробелы/переносы, как многие могут подумать, но и много правил отвечающих за безопасность, кеширование и прочее.
Как установить WPCS?
WPCS можно установить через composer
или с github-репозитория.
Установка через composer
:
1 | composer require wp-coding-standards /wpcs --dev |
После установки любого стандарта, необходимо его добавить в область видимости phpcs
. Чтобы не делать этого вручную, можно поставить еще 1 пакет, который это будет делать за вас:
1 | composer require dealerdirect /phpcodesniffer-composer-installer --dev |
И теперь проверяем файл или пытаемся исправить его:
12 | vendor/bin/phpcs --standard=WordPress path/to/some/file.php vendor/bin/phpcbf --standard=WordPress path/to/some/file.php |
Как настроить PHPStorm?
PHPStorm -> Settings -> Languages & Frameworks -> PHP -> CLI Interpreter выбираем текущую версию PHP.
PHPStorm -> Settings -> Languages & Frameworks -> PHP -> Quality Tools -> PHP_CodeSniffer -> Configuration и нажимаем на ‘…‘
В PHP_CodeSniffer path указываем путь:
И в Path to phpcbf:
Нажмите Validate, чтобы убедиться, что пути указаны правильно.
PHPStorm -> Settings -> Editor -> Inspection -> Quality Tools -> PHP_CodeSniffer validation:
Ставим голочку Show sniff name
В списке Coding Standard. Должны появится такие наборы: WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra. Выбираем WordPress и сохраняем.
Теперь при нарушении вами стандартов кодирования, в редакторе, строки будут подчеркнуты. При наведении на подчеркнутую строку вы увидите ошибку.
Например:
phpcs: WordPress.Security.NonceVerification.Missing: Processing form data without nonce verification.
Где WordPress.Security.NonceVerification.Missing — название сниффа а Processing form data without nonce verification. — его описание.
Можно ли точечно отключать WPCS?
Бывают задачи, которые нельзя написать код без нарушение WPCS. Например я хочу сделать запрос в свою таблицу:
В текущем примере нарушается 3 условия:
- WordPress.DB.DirectDatabaseQuery.NoCaching
- WordPress.DB.PreparedSQL.NotPrepared
- WordPress.DB.DirectDatabaseQuery.DirectQuery
Если сделать кеширование и подготовить запрос мы можем, то что делать с прямым запросом? А все просто. Нужно добавить игнор этой ошибки на текущую строку. Этот игнор нам говорит о том, что разработчик действительно понимает, зачем он делает этот запрос в БД. Своего рода подпись программиста о написаной строке или блоке кода.
Хороший пример запроса с выполнением всех требований WPCS выглядит так:
phpcs:ignore — работает на следующую строку кода, но бывают ситуации, когда нужно заблокировать проверку на небольшой блок кода и тогда можем использовать phpcs:disabled, но важно не забывать включить проверку обратно:
Свои coding standards на базе WPCS?
Я рекомендую на проекты среднего размера использовать свои собственные стандарты кодирования. Делается это очень легко. Нужно создать файл phpcs.xml
:
- <ruleset name=»MyCS»> — название CS;
- <description>Custom coding standards.</description> — описание CS;
- <config name=»installed_paths» value=»vendor/wp-coding-standards/wpcs»/> — список путей, через запятую, в которых нужно искать уже готовые наборы правил
- <rule ref=»WordPress»/> — подключаем WPCS
Короткий синтаксис для массивов
Теперь наши собственные стандарты кодирования полностью копируют WordPress Coding Standards. Но теперь мы можем добавить свои правила. Например, мне не нравится использовать длинный синтаксис для массивов (array( ... )
) и я хочу использовать короткий формат ([ ... ]
).
Именование классов и файлов по PSR4
Цикломатическая сложность
Цикломатическая сложность — это метрика программного обеспечения, используемая для обозначения сложности программы. Это количественная мера количества линейно независимых путей в исходном коде программы.
Wikipedia
Данная метрика поможет писать более простые функции и методы.
- При цикломатической сложности выше 4 вы увидите warning
- При цикломатической сложности выше 5 вы увидите ошибку
Уровень вложенности
При уровне вложенности выше 1 вы увидите ошибку.
Данный код вызовет ошибку по CS:
Его необходимо отрефакторить примерно так, чтобы уменьшить уровень вложенности:
Добавить свой CS в PHP Storm
File -> Settings -> Editor -> Inspection -> Quality Tools -> PHP_CodeSniffer
В списке Coding standard выбираем Custom и указываем путь к нашему phpcs.xml
CS в Travis CI
Добавляем собственный билд, для репозитория, который будет проверять CS после добавления кода в репозиторий. Для этого в репозитории нужно создать .travis.yml
:
Все сводится к одной строке, которая проверяет все файлы в проекте.
Заходим в аккаунт на https://travis-ci.org/, подключаем свой репозиторий и включаем его поддержку.
Теперь при слиянии веток буде вызываться файл .travis.yml
. В админке Travis CI можно будет видеть, удовлетворяет ли новый требованиям нашего стандарта.
CS в GitHub Actions
Создаем в вашем проекте .github/workflows/php.yml
:
После событий push
и pull_request
будут проверяться стандарты кодирования.
Источник: WP Punk