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:

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

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

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

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

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/vendor/squizlabs/php_codesniffer/bin/phpcs

И в Path to phpcbf:

path/to/vendor/squizlabs/php_codesniffer/bin/phpcsbf

Нажмите 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. К примеру я хочу сделать запрос в таблицу:

global $wpdb;$id = 15;$my_query = $wpdb->get_results( 'SELECT name FROM my_table WHERE id='. $id);

В текущем примере нарушается 3 условия:

  • WordPress.DB.DirectDatabaseQuery.NoCaching
  • WordPress.DB.PreparedSQL.NotPrepared
  • WordPress.DB.DirectDatabaseQuery.DirectQuery

Если сделать кеширование и подготовить запрос мы можем, то что делать с прямым запросом? А все просто. Необходимо добавить игнор данной ошибки на текущую строку. Этот игнор нам говорит о том, что разработчик действительно понимает, зачем он делает этот запрос в БД. Своего рода подпись программиста о написаной строке или блоке кода.

Хороший пример запроса с выполнением всех требований WPCS выглядит так:

global $wpdb;$id = 15;$my_query = wp_cache_get( 'my_query');if(! $my_query) {$my_query = $wpdb->get_results( //phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery$wpdb->prepare( 'SELECT name FROM my_table WHERE id=%d', $id));wp_cache_set( 'my_query', $my_query);}

phpcs:ignore — работает на следующую строку кода, но бывают ситуации, когда необходимо заблокировать проверку на небольшой блок кода и тогда можем использовать phpcs:disabled, но важно не забывать включить проверку обратно:

//phpcs:disable WordPress.DB.DirectDatabaseQuery.DirectQuery$my_query = $wpdb->get_results( $wpdb->prepare( 'SELECT name FROM my_table WHERE id=%d', $id));//phpcs:enable WordPress.DB.DirectDatabaseQuery.DirectQuery

Свои coding standards на базе WPCS?

Я рекомендую на проекты среднего размера использовать ваши собственные стандарты кодирования. Делается это без труда. Необходимо создать файл phpcs.xml:

<?xml version="1.0"?><ruleset name="MyCS"><description>Custom coding standards.</description><config name="installed_paths" value="vendor/wp-coding-standards/wpcs"/><rule ref="WordPress"/></ruleset>
  • <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(...)) и я хочу использовать короткий формат( [... ] ).

<?xml version="1.0"?><ruleset name="MyCS"><description>Custom coding standards.</description><config name="installed_paths" value="vendor/wp-coding-standards/wpcs"/><rule ref="WordPress"/><!-- Allow short array syntax --><rule ref="Generic.Arrays.DisallowShortArraySyntax.Found"><severity>0</severity></rule><rule ref="Generic.Arrays.DisallowLongArraySyntax.Found"/></ruleset>

Именование классов и файлов по PSR4

<?xml version="1.0"?><ruleset name="MyCS"><description>Custom coding standards.</description><config name="installed_paths" value="vendor/wp-coding-standards/wpcs"/><rule ref="WordPress"><!-- PSR4 autoload --><exclude name="WordPress.Files.FileName.InvalidClassFileName"/><exclude name="WordPress.Files.FileName.NotHyphenatedLowercase"/></rule><!-- Allow short array syntax --><rule ref="Generic.Arrays.DisallowShortArraySyntax.Found"><severity>0</severity></rule><rule ref="Generic.Arrays.DisallowLongArraySyntax.Found"/></ruleset>

Цикломатическая сложность

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

Wikipedia

Данная метрика поможет писать более простые возможности и способы.

<?xml version="1.0"?><ruleset name="MyCS"><description>Custom coding standards.</description><config name="installed_paths" value="vendor/wp-coding-standards/wpcs"/><rule ref="WordPress"><!-- PSR4 autoload --><exclude name="WordPress.Files.FileName.InvalidClassFileName"/><exclude name="WordPress.Files.FileName.NotHyphenatedLowercase"/></rule><rule ref="Generic.Metrics.CyclomaticComplexity"><properties><property name="complexity" value="4"/><property name="absoluteComplexity" value="5"/></properties></rule><!-- Allow short array syntax --><rule ref="Generic.Arrays.DisallowShortArraySyntax.Found"><severity>0</severity></rule><rule ref="Generic.Arrays.DisallowLongArraySyntax.Found"/></ruleset>
  • При цикломатической сложности выше 4 вы увидите warning
  • При цикломатической сложности выше 5 вы увидите ошибку

Уровень вложенности

<?xml version="1.0"?><ruleset name="MyCS"><description>Custom coding standards.</description><config name="installed_paths" value="vendor/wp-coding-standards/wpcs"/><rule ref="WordPress"><!-- PSR4 autoload --><exclude name="WordPress.Files.FileName.InvalidClassFileName"/><exclude name="WordPress.Files.FileName.NotHyphenatedLowercase"/></rule><rule ref="Generic.Metrics.CyclomaticComplexity"><properties><property name="complexity" value="4"/><property name="absoluteComplexity" value="5"/></properties></rule><rule ref="Generic.Metrics.NestingLevel"><properties><property name="absoluteNestingLevel" value="1"/></properties></rule><!-- Allow short array syntax --><rule ref="Generic.Arrays.DisallowShortArraySyntax.Found"><severity>0</severity></rule><rule ref="Generic.Arrays.DisallowLongArraySyntax.Found"/></ruleset>

При уровне вложенности выше 1 вы увидите ошибку.

Данный код вызовет ошибку по CS:

function awesome_function( $items ) {if ( is_array( $items ) {foreach( $items as $item ) {// ...}}}

Его надо отрефакторить примерно так, чтобы уменьшить уровень вложенности:

function awesome_function( $items ) {if ( ! is_array( $items ) {return false;}foreach( $items as $item ) {// ...}}

Добавить CS в PHP Storm

File -> Settings -> Editor -> Inspection -> Quality Tools -> PHP_CodeSniffer

В списке Coding standard выбираем Custom и указываем путь к нашему phpcs.xml

CS в Travis CI

Добавляем собственный билд, для репозитория, который будет проверять CS после добавления кода в репозиторий. Для этого в репозитории необходимо создать . travis.yml :

language: phpmatrix: fast_finish: true include: - php: '7.3' env:       - DEV="--no-dev" SNIFF=1cache:  directories:    - vendor    - $HOME/.composer/cachebefore_script:  - phpenv rehash  - composer install $DEVscript:  - if [[ "$SNIFF" == "1" ]]; then vendor/bin/phpcs --standard=phpcs.xml .; fi

Все сводится к одной строке, которая проверяет все файлы в проекте.

vendor/bin/phpcs --standard=phpcs.xml .

Заходим в аккаунт на
https://travis-ci.org/ , подключаем репозиторий и включаем его поддержку.

Сейчас при слиянии веток буде вызываться файл .travis.yml . В админке Travis CI можно без проблем будет видеть, удовлетворяет ли новый требованиям нашего стандарта.

CS в GitHub Actions

Создаем в проекте .github/workflows/php.yml :

name: My GH Actionson: [push, pull_request]jobs:  build:    runs-on: ubuntu-latest steps:    - uses: actions/checkout@v2    - name: Install dependencies run: composer install --prefer-dist --no-progress --no-suggest    - name: Run CS run: vendor/bin/phpcs --standard=phpcs.xml .

После событий push и pull_request будут проверяться стандарты кодирования.

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *