WordPress Coding Standards(WPCS)

Содержание скрыть

1 Как установить WPCS?

2 Как настроить PHPStorm?

3 Как отключить некоторые правила WPCS?

4 Что делать, если нельзя выполнить требование WPCS?

5 WPCS и Travis CI

6 WPCS и GitHub Actions

WPCS — это набор правил PHP_CodeSniffer (сниффы) для проверки кода, разработанного для WordPress. Он обеспечивает качество кода и соблюдение соглашений официальных стандартов кода для WordPress.

Если вы работаете в команде из более 1-го человека, то стоит подумать о едином стандарте коде (code style). Даже если вы в своей команде смогли договорится о каком-то стандарте, то очень сложно его придерживаться. Для этого есть специальные инструменты, которые называются линтеры, которые существуют для каждого языка программирования.

Линтер – утилита для проверки код на соответствие стандартам и спецификациям языка. К примеру, для Python он существует в виде пакета Pylint, для PHP — PHP CodeSniffer, для JavaScript – ESHint, для Java – FindBugs и т.д.

Как установить WPCS?

WPCS можно установить через composer или с github-репозитория.

Установка через composer:

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

Теперь можно проверить работу wpcs. Добавляем стандартны:

php vendor/bin/phpcs --config-set installed_paths vendor/wp-coding-standards/wpcs

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

php vendor/bin/phpcs -p path/to/some/file.php --standard=WordPress
php vendor/bin/phpcbf -p path/to/some/file.php --standard=WordPress

Как настроить PHPStorm?

File -> 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, чтобы убедиться, что пути указаны правильно.

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

Ставим голочку Show sniff name

Installed standard paths: path/to/vendor/wp-coding-standards/wpcs/

Теперь обновляем Coding Standard. Должны появится такие наборы: WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra. Выбираем WordPress и сохраняем.

Теперь при нарушении вами code style в шторме строки будут подчеркнуты. При наведении на подчеркнутую строку вы увидите ошибку.

Например:

phpcs: WordPress.Security.NonceVerification.Missing: Processing form data without nonce verification.

Вначале нам говорится о том, какое правило нарушено и затем объяснение человеческим языком.

Как отключить некоторые правила WPCS?

Есть немного сомнительные правила, но в целом, если разобраться, то все они имеют в себе какой-то смысл. За год использования я не смирился только с 1 правилом, поэтому покажу, как его отключить.

Правило: phpcs: Generic.Arrays.DisallowShortArraySyntax.Found: Short array syntax is not allowed. Говорит о том, что в коде нельзя использовать сокращенный вид массивов [], а нужно вместо этого использовать array(). Я считаю это правило устаревшим и поэтому решил его отключить.

Для изменений WPCS в своем проекте нужно создать phpcs.xml

<?xml version="1.0"?>
<ruleset name="WordPress Plugin Coding Standards">
    <description>A custom set of code standard rules to check for WordPress plugins.</description>

    <config name="installed_paths" value="vendor/wp-coding-standards/wpcs"/>

    <rule ref="WordPress"/>
    <!-- https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Customizable-sniff-properties -->

    <exclude-pattern>*/.make/*</exclude-pattern>
    <exclude-pattern>*/assets/*</exclude-pattern>
    <exclude-pattern>*/css/*</exclude-pattern>
    <exclude-pattern>*/dist/*</exclude-pattern>
    <exclude-pattern>*/js/*</exclude-pattern>
    <exclude-pattern>*/languages/*</exclude-pattern>
    <exclude-pattern>*/lib/*</exclude-pattern>
    <exclude-pattern>*/src/*</exclude-pattern>
    <exclude-pattern>*/tests/*</exclude-pattern>
    <exclude-pattern>*/vendor/*</exclude-pattern>
    <exclude-pattern>*.js</exclude-pattern>
    <exclude-pattern>*.mo</exclude-pattern>
    <exclude-pattern>*.po</exclude-pattern>
    <exclude-pattern>*.twig</exclude-pattern>
    <exclude-pattern>*.css</exclude-pattern>
    <exclude-pattern>*.scss</exclude-pattern>

    <rule ref="Generic.Arrays.DisallowShortArraySyntax.Found">
        <severity>0</severity>
    </rule>

</ruleset>

Разберем подробнее:

<ruleset name="WordPress Plugin Coding Standards">

В атрибуте name указываем название нашего CS.

<config name="installed_paths" value="vendor/wp-coding-standards/wpcs"/>

В дериктиве <config name=»installed_paths»> указываем в value путь к стандарту WordPress

<exclude-pattern>*.css</exclude-pattern>

Так же исключим из какую-то директорию на проверку wpcs.

<rule ref="Generic.Arrays.DisallowShortArraySyntax.Found">
    <severity>0</severity>
</rule>

Отключаем правило, которое запрещает использовать короткий синтаксис для массивов.

Теперь нужно в PHP Storm указать путь к нашему новому CS.

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

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

Что делать, если нельзя выполнить требование WPCS?

Бывают задачи, которые нельзя выполнить без нарушение WPCS. Например я хочу сделать запрос в свою таблицу:

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

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

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

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

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

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

WPCS и Travis CI

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

language: php

matrix:
  fast_finish: true
  include:
    - php: '7.3'
      env:
        - DEV="--no-dev" SNIFF=1

cache:
  directories:
    - vendor
    - $HOME/.composer/cache

before_script:
  - phpenv rehash
  - composer install $DEV

script:
  - if [[ "$SNIFF" == "1" ]]; then vendor/bin/phpcs -p -s --colors --standard=phpcs.xml .; fi

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

vendor/bin/phpcs -p -s --colors --standard=phpcs.xml .

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

Теперь при слиянии веток буде вызываться файл .travis.yml. В админке travis-ci можно будет видеть удачно или не удачно прошел процесс. В случае неудачи пул реквест не будет завершен.

WPCS и GitHub Actions

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

name: PHP Composer

on: [push, pull_request]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2

    - name: Validate composer.json and composer.lock
      run: composer validate

    - name: Install dependencies
      run: composer install --prefer-dist --no-progress --no-suggest

    - name: Run test suite
      run: vendor/bin/phpcs -p -s --colors --standard=phpcs.xml .

При событие push и pull_request будут выполняться проверки composer’а, устанавливаться все пакеты и запускаться проверка wpcs.

WordPress Coding Standards(WPCS)

Как установить WPCS?

Как настроить PHPStorm?

Как отключить некоторые правила WPCS?

Что делать, если нельзя выполнить требование WPCS?

WPCS и Travis CI

WPCS и GitHub Actions

Понравилось это:

Похожее

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

Как установить WPCS?

Как настроить PHPStorm?

Как отключить некоторые правила WPCS?

Что делать, если нельзя выполнить требование WPCS?

WPCS и Travis CI

WPCS и GitHub Actions

Sharing is caring

Понравилось это:

Похожее

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