Использование PHP CodeSniffer с WordPress: установка и использование правил WordPress

() translation by (you can also view the original English article)

Если вы только присоединяетесь к этой серии, мы обсуждаем тему кодовых душков, способы их рефакторинга и инструменты, которые помогут нам автоматизировать некоторые рутины, связанные с этим, особенно в программировании на PHP.

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

Эти статьи:

Короче говоря, в приведенных выше статьях будет представлена концепция кодовых запахов, которую мы определяем следующим образом:

[A] запах кода, также известный как плохой запах, в коде компьютерного программирования, относится к любому признаку в исходном коде программы, который, возможно, указывает на более глубокую проблему.

И я проведу вас через шаги, необходимые для установки PHP_CodeSniffer на вашем компьютере.

Но если вы зашли так далеко, то я предполагаю, что вы разработчик WordPress, и вы заинтересованы в том, чтобы PHP CodeSniffer был настроен таким образом, чтобы он мог вынюхивать любые проблемы в вашем коде, связанные с стандартами кодирования WordPress.

Это хорошо! Потому что в оставшейся части этой статьи мы рассмотрим именно это.

Предпосылки

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

Версия PHP (предпочтительно 5.6.10 или более поздняя)
PHP CodeSniffer
Composer

Все это подробно описано во всех предыдущих статьях серии, но если вы добрались до этого момента и владеете командной строкой, то это должно быть подгонкой по сравнению с тем, что мы сделали до сих пор.

Со всем сказанным, давайте начнем.

Правила WordPress для PHP CodeSniffer

Во-первых, найдите правила стандартов кодирования WordPress на GitHub. Их там легко найти.

Вы можете прочитать все подробности на странице проекта, но вот самое главное, чем я хотел бы поделиться:

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

Я хотел бы обратить ваше внимание на фразу, что это относится к «официальным стандартам кодирования WordPress». Обратите внимание, что эти правила основаны на стандартах кодирования WordPress. То есть, вы не можете официально ссылаться на них.

Если вы хотите найти способ просмотреть правила, которые определяет WordPress, ознакомьтесь с этой статьей в Codex. Им легко следовать, легко читать, но многое нужно запомнить. К счастью, у нас есть набор правил, указанный выше.

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

1. Установите правила WordPress.

Предполагая, что вы правильно установили PHP CodeSniffer, давайте добавим в программное обеспечение правила WordPress. В этом уроке я собираюсь делать все с помощью командной строки, чтобы быть максимально независимым от платформы. Я расскажу несколько слов об IDE и правилах в конце серии.

Откройте свой терминал и перейдите туда, где у вас установлена копия PHP CodeSniffer. Если вы следовали вместе с этой серией обучающих программ, то, скорее всего, вспомните, что у нас есть файл composer.json, который установит все за нас. Если нет, не забудьте создать composer.json в корневом каталоге вашего проекта и добавить в него:

{
    "require": {
        "squizlabs/php_codesniffer": "2.*"
    }
}

После этого запустите $ composer update из вашего терминала, и у вас будет все, что вам нужно чтобы начать. Чтобы проверить установку, выполните следующую команду:

1	$ vendor/bin/phpcs --version

И вы должны получить что-то вроде следующего вывода:

1	PHP_CodeSniffer version 2.6.0 (stable) by Squiz (https://www.squiz.net)

Отлично. Далее, давайте установим правила WordPress. Поскольку мы используем Composer (и будем продолжать это делать), это очень легко сделать.

Выполните следующую команду из корневого каталога вашего проекта:

1	composer create-project wp-coding-standards/wpcs:dev-master --no-dev

Обратите внимание, что может появиться запрос со следующим вопросом:

1	Do you want to remove the existing VCS (.git, .svn..) history? [Y,n]?

Если вы знаете, что вы делаете, тогда не стесняйтесь идти дальше и выберите «n»; В противном случае, лучше нажимать 'y'.

2. Добавление правил в PHP CodeSniffer

Теперь, когда PHP CodeSniffer установлен и установлены правила WordPress, мы должны убедиться, что PHP CodeSniffer знает о нашем новом наборе правил. Для этого нам нужно ввести следующую команду в командной строке.

В корневом каталоге вашего проекта введите следующую команду:

1	$ vendor/bin/phpcs --config-set installed_paths wpcs

Чтобы убедиться, что новые правила добавлены, мы можем попросить PHP CodeSniffer сообщить нам набор правил, которые он в настоящее время имеет. В терминале введите следующую команду:

1	$ vendor/bin/phpcs -i

И вы должны увидеть следующий результат (или что-то очень похожее):

1	The installed coding standards are MySource, PEAR, PHPCS, PSR1, PSR2, Squiz, Zend, WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra and WordPress-VIP

Обратите внимание, что в строке выше мы имеем несколько наборов правил относительно WordPress. Очень красиво, не так ли? Конечно, давайте посмотрим, как это все сработает, когда мы запустим наборы правил чтобы проверить плагин, такой как например Hello Dolly.

3. Запуск PHP CodeSniffer для проверки проектов WordPress

Предполагая, что вы работаете в каталоге, который включает плагин WordPress, вы можете пропустить следующий шаг. Если, с другой стороны, у вас нет копии сценария WordPress, файла, темы или плагина, установленных в каталоге проекта, перейдите вперед и скопируйте его в свой каталог проекта.

Как уже упоминалось, мы будем тестировать плагин Hello Dolly.

Чтобы запустить PHP CodeSniffer с правилами WordPress в отношении файлов в каталоге плагина, введите в терминале следующую команду:

1	$ vendor/bin/phpcs --standard=WordPress hello-dolly

Это приведет к выводу, который должен соответствовать тому, что вы видите здесь:

FILE: /Users/tommcfarlin/Desktop/tutsplus_demo/hello-dolly/hello.php
----------------------------------------------------------------------
FOUND 14 ERRORS AFFECTING 14 LINES
----------------------------------------------------------------------
  2 | ERROR | Missing short description in doc comment
  5 | ERROR | There must be exactly one blank line after the file
    |       | comment
  6 | ERROR | Empty line required before block comment
 15 | ERROR | You must use "/**" style comments for a function
    |       | comment
 46 | ERROR | Inline comments must end in full-stops, exclamation
    |       | marks, or question marks
 49 | ERROR | Inline comments must end in full-stops, exclamation
    |       | marks, or question marks
 53 | ERROR | Inline comments must end in full-stops, exclamation
    |       | marks, or question marks
 54 | ERROR | You must use "/**" style comments for a function
    |       | comment
 56 | ERROR | Expected next thing to be an escaping function (see
    |       | Codex for 'Data Validation'), not '"<p
    |       | id='dolly'>$chosen</p>"'
 59 | ERROR | Inline comments must end in full-stops, exclamation
    |       | marks, or question marks
 62 | ERROR | Inline comments must end in full-stops, exclamation
    |       | marks, or question marks
 63 | ERROR | You must use "/**" style comments for a function
    |       | comment
 64 | ERROR | Inline comments must end in full-stops, exclamation
    |       | marks, or question marks
 67 | ERROR | Expected next thing to be an escaping function (see
    |       | Codex for 'Data Validation'), not '"
    |       | '
----------------------------------------------------------------------

Конечно, некоторые из этих вещей могут измениться в зависимости от того, когда вы читаете этот урок.

Ошибки должны быть достаточно ясными относительно того, что необходимо исправить:

Первый столбец обозначает строку, в которой обнаружена проблема.
Второй столбец определяет, есть ли ошибка или предупреждение.
В третьей колонке объясняется проблема и что ожидается от кода.

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

4. Рефакторинг Hello Dolly

Обратите внимание, что плагин, прежде чем мы начнем работать над ним, включает в себя следующий исходный код:

<?php
/**
 * @package Hello_Dolly
 * @version 1.6
 */
/*
Plugin Name: Hello Dolly
Plugin URI: https://wordpress.org/plugins/hello-dolly/
Description: This is not just a plugin, it symbolizes the hope and enthusiasm of an entire generation summed up in two words sung most famously by Louis Armstrong: Hello, Dolly. When activated you will randomly see a lyric from <cite>Hello, Dolly</cite> in the upper right of your admin screen on every page.
Author: Matt Mullenweg
Version: 1.6
Author URI: http://ma.tt/
*/

function hello_dolly_get_lyric() {
    /** These are the lyrics to Hello Dolly */
  $lyrics = "Hello, Dolly
Well, hello, Dolly
It's so nice to have you back where you belong
You're lookin' swell, Dolly
I can tell, Dolly
You're still glowin', you're still crowin'
You're still goin' strong
We feel the room swayin'
While the band's playin'
One of your old favourite songs from way back when
So, take her wrap, fellas
Find her an empty lap, fellas
Dolly'll never go away again
Hello, Dolly
Well, hello, Dolly
It's so nice to have you back where you belong
You're lookin' swell, Dolly
I can tell, Dolly
You're still glowin', you're still crowin'
You're still goin' strong
We feel the room swayin'
While the band's playin'
One of your old favourite songs from way back when
Golly, gee, fellas
Find her a vacant knee, fellas
Dolly'll never go away
Dolly'll never go away
Dolly'll never go away again";

	// Here we split it into lines
	$lyrics = explode( "\n", $lyrics );

	// And then randomly choose a line
	return wptexturize( $lyrics[ mt_rand( 0, count( $lyrics ) - 1 ) ] );
}

// This just echoes the chosen line, we'll position it later
function hello_dolly() {
	$chosen = hello_dolly_get_lyric();
	echo "<p id='dolly'>$chosen</p>";
}

// Now we set that function up to execute when the admin_notices action is called
add_action( 'admin_notices', 'hello_dolly' );

// We need some CSS to position the paragraph
function dolly_css() {
	// This makes sure that the positioning is also good for right-to-left languages
	$x = is_rtl() ? 'left' : 'right';

	echo "
	<style type='text/css'>
	#dolly {
		float: $x;
		padding-$x: 15px;
		padding-top: 5px;		
		margin: 0;
		font-size: 11px;
	}
	</style>
	";
}

add_action( 'admin_head', 'dolly_css' );

?>

Код довольно простой, поскольку он использует только несколько базовых функций PHP, и Мэтт проделал хорошую работу по комментированию кода.

Но, учитывая 14 ошибок, обнаруженных CodeSniffer, давайте реорганизуем плагин. Принимая во внимание ошибки, которые мы получили, и то, что от нас ожидают увидеть, давайте обратимся к каждой из них.

После этого плагин должен выглядеть следующим образом:

<?php
/**
 * This is a plugin that symbolizes the hope and enthusiasm of an entire
 * generation summed up in two words sung most famously by Louis Armstrong.
 *
 * @package Hello_Dolly
 * @version 1.6
 *
 * @wordpress-plugin
 * Plugin Name: Hello Dolly
 * Plugin URI: https://wordpress.org/plugins/hello-dolly/
 * Description: This is not just a plugin, it symbolizes the hope and enthusiasm of an entire generation summed up in two words sung most famously by Louis Armstrong: Hello, Dolly. When activated you will randomly see a lyric from <cite>Hello, Dolly</cite> in the upper right of your admin screen on every page.
 * Author: Matt Mullenweg
 * Version: 1.6
 * Author URI: http://ma.tt/
 */

/**
 * Defines the lyrics for 'Hello Dolly'.
 *
 * @return string A random line of from the lyrics to the song.
 */
function hello_dolly_get_lyric() {
    /** These are the lyrics to Hello Dolly */
    $lyrics = "Hello, Dolly
Well, hello, Dolly
It's so nice to have you back where you belong
You're lookin' swell, Dolly
I can tell, Dolly
You're still glowin', you're still crowin'
You're still goin' strong
We feel the room swayin'
While the band's playin'
One of your old favourite songs from way back when
So, take her wrap, fellas
Find her an empty lap, fellas
Dolly'll never go away again
Hello, Dolly
Well, hello, Dolly
It's so nice to have you back where you belong
You're lookin' swell, Dolly
I can tell, Dolly
You're still glowin', you're still crowin'
You're still goin' strong
We feel the room swayin'
While the band's playin'
One of your old favourite songs from way back when
Golly, gee, fellas
Find her a vacant knee, fellas
Dolly'll never go away
Dolly'll never go away
Dolly'll never go away again";

	// Here we split it into lines.
	$lyrics = explode( "\n", $lyrics );

	// And then randomly choose a line.
	return wptexturize( $lyrics[ mt_rand( 0, count( $lyrics ) - 1 ) ] );
}

add_action( 'admin_notices', 'hello_dolly' );
/**
 * This just echoes the chosen line, we'll position it later. This function is
 * set up to execute when the admin_notices action is called.
 */
function hello_dolly() {

	$chosen = hello_dolly_get_lyric();
	echo "<p id='dolly'>$chosen</p>"; // WPCS: XSS OK.

}

add_action( 'admin_head', 'dolly_css' );
/**
 * Add some CSS to position the paragraph.
 */
function dolly_css() {

	/**
	 *This makes sure that the positioning is also good for right-to-left languages.
	 */
	$x = is_rtl() ? 'left' : 'right';
	echo "<style type='text/css'> #dolly { float: $x; padding-$x: 15px; padding-top: 5px; margin: 0; font-size: 11px; } </style> "; // WPCS: XSS OK.

}

Обратите внимание, что плагин продолжает работать, и код стал немного чище. Наконец, давайте проверим, что плагин проходит тест PHP CodeSniffer. Давайте снова запустим код, который мы использовали выше, чтобы сначала оценить плагин.

1	$ vendor/bin/phpcs --standard=WordPress hello-dolly

И вывод, который мы видим:

1	Skyhopper5:tutsplus_demo tommcfarlin$

Именно так: вывода не должно быть. Вместо этого должно быть возвращение к стандартной командной строке.

Отлично. Плагин был доведен до стандарта. Вот почему наличие анализатора кода настолько ценно: он находит ошибки в вашем коде на основе правил, которые вы определяете, а затем сообщает о любых возможных ошибках.

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

Вывод

И с этим мы завершаем серию использования PHP CodeSniffer. Напомним, что во всей серии мы рассмотрели идею запахов кода, способы их рефакторинга и инструменты, которые доступны нам при работе с PHP-приложениями.

В этой статье мы увидели, как мы можем использовать предоставленный набор правил для стандартов кодирования WordPress для оценки нашего кода при работе над новым или существующим проектом. Обратите внимание, что некоторые IDE поддерживают возможность выполнения правил при написании кода.

Хотя это выходит за рамки данного учебника, вы можете найти ресурсы для этого в разных местах в Интернете. Просто найдите свою IDE по имени, определите ее поддержку для PHP CodeSniffer, а затем обязательно установите правила WordPress, как мы подробно рассказали в этом учебнике.

Если вам понравилась эта статья или эта серия, вам может быть интересно проверить другие вещи, которые я написал как на странице моего профиля, так и в моем блоге. Вы также можете следить за мной в Twitter на @tommcfarlin, где я часто общаюсь и обмениваюсь различными методами разработки программного обеспечения в контексте WordPress.

С учетом сказанного, не стесняйтесь оставлять любые вопросы или комментарии в фиде ниже, и я постараюсь ответить на каждый из них.