WordPress Coding Standards (WPCS)

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

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

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

3 Можно ли точечно отключать WPCS?

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

4.1 Короткий синтаксис для массивов

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

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

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

4.5 Добавить свой CS в PHP Storm

5 CS в Travis CI

6 CS в GitHub Actions

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: 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 --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 Actions

on: [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 будут проверяться стандарты кодирования.

Источник: WP Punk

Источник: https://www.kobzarev.com/wordpress/wpcs/

WordPress Coding Standards (WPCS)

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

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

Можно ли точечно отключать WPCS?

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

Короткий синтаксис для массивов

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

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

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

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

CS в Travis CI

CS в GitHub Actions

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

Похожее

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

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

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

Можно ли точечно отключать WPCS?

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

Короткий синтаксис для массивов

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

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

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

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

CS в Travis CI

CS в GitHub Actions

Sharing is caring

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

Похожее

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