WordPress Coding Standards (WPCS)

Click here to view original web page at www.kobzarev.com
Обложка к записи WordPress Coding Standards (WPCS)

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:

1composer require wp-coding-standards/wpcs --dev

После установки любого стандарта, необходимо его добавить в область видимости phpcs. Чтобы не делать этого вручную, можно поставить еще 1 пакет, который это будет делать за вас:

1composer require dealerdirect/phpcodesniffer-composer-installer --dev

И теперь проверяем файл или пытаемся исправить его:

12vendor/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