Стандарты оформления — это набор правил, в которых оговаривается внешний вид кода: где ставятся пробелы, где нужны пустые строки, какие кавычки использовать и так далее.
Они помогают приводить код к единому виду. Это важно для командной работы, изучения или доработки open-source программ — разбираться в чужом коде проще и быстрее. Потратив немного времени на внедрение стандартов оформления в вашей работе вы получите гарантированный выигрыш в продуктивности: читать чужой код будет так же легко, как и свой.
Существует несколько стандартов оформления кода. Для PHP наиболее распространены — Zend Coding Standard, PEAR и PSR. В статье рассмотрим способ автоматического оформления кода по стандарту PSR. Для этого существует удобная библиотека php-cs-fixer.
Установка
Установить php-cs-fixer можно глобально или локально. При локальной установке библиотека будет сохранена в папке vendor вашего проекта.
Cкачать программу можно напрямую из репозитория, но мы для удобства воспользуемся менеджером пакетов Composer.
Локальная установка:
composer require friendsofphp/php-cs-fixer
Глобальная установка:
composer global require friendsofphp/php-cs-fixer
Глобальная установка бывает удобна для использования в нескольких проектах, но с разными стилистическими правилами. Чтобы в терминале использовать команду php-cs-fixer, необходимо указать путь в переменной окружения PATH. Пользователи Unix систем могут это сделать прямо в терминале с помощью команды. Пакеты, установленные глобально, находятся в папке $HOME/.composer/vendor/
export PATH="$PATH:$HOME/путь-к-папке-библиотеки"
Способ задания переменной окружения PATH для пользователей Windows описан здесь.
Запуск
Исправить оформление кода можно либо в отдельном файле, либо во всех файлах указанной папки. Делается это с помощью команды fix. По умолчанию используются стандарты PSR-1 и PSR-2.
При глобальной установке:
php-cs-fixer fix путь-к-файлу.php
php-cs-fixer fix путь-к-папке/
В случае локальной установки вам необходимо обратиться к скомпилированному файлу:
/path/to/project/vendor/bin/php-cs-fixer fix путь-к-файлу.php
Настройка
Для описания правил оформления кода существует параметр --rules, который можно передать в консоли при выполнении команды.
php-cs-fixer fix /path/to/project --rules=@PSR2, full_opening_tag, indentation_type
Чтобы каждый раз не передавать --rules, создадим конфигурационный файл .php_cs в корне проекта, в котором перечислим набор правил.
Пример базового файла с настройками.
<?php
return PhpCsFixer\Config::create()
->setRules([
'@PSR2' => true,
'strict_param' => true,
'array_syntax' => ['syntax' => 'short'],
])
->setUsingCache(false)
->setFinder(
PhpCsFixer\Finder::create()
->in(__DIR__)
);
;
setRules задает набор правил оформления. Список доступных правил описан здесь.
setUsingCache ускоряет выполнение программы, запоминая время и список файлов, чтобы в следующий раз при запуске исправлять только те файлы, которые менялись.
setFinder определяет папку, в которой будут исправлены файлы. Если нужно исключить папку, то для этого добавляется параметр exclude('somedir').
Теперь при запуске скрипта применятся набор правил оформления, заданный в .php_cs. Пример исходного файла до автоисправления
class Auth {
const SUPPORTED_TYPES = ['Bearer']; const SOME_ARRAY = array();
/**
* Authenticate user by JWT
* @param Request $req
* @param Response $res
* @param $next
* @return Response - with 403 status if auth failed
*/
public function jwt(Request $req, Response $res, $next): Response {
try {
$authHeader = $req->getHeader('Authorization');
if ( empty($authHeader[0]) ) {
throw new AuthException("HTTPAuth header is missing");
}
Log::instance()->notice($authHeader[0]);
.....
}
Исправленный файл
class Auth
{
const SUPPORTED_TYPES = ['Bearer'];
const SOME_ARRAY = []; // array заменили на []
/**
* Authenticate user by JWT
*
* @param Request $req
* @param Response $res
* @param $next
*
* @return Response - with 403 status if auth failed
*/
public function jwt(Request $req, Response $res, $next): Response
{
try {
$authHeader = $req->getHeader('Authorization');
if (empty($authHeader[0])) {
throw new AuthException('HTTPAuth header is missing');
}
Log::instance()->notice($authHeader[0]);
.....
}
Удобство восприятия — важное качество создаваемого кода. Эффективность командной работы повышается, когда все разработчики пишут в едином стиле. Изучать сторонние библиотеки и решения проще, если их код соответствует стандартам.
Следить за оформлением и автоматически исправлять ошибки помогают скрипты, такие как PHP CS Fixer. Также рекомендуется настроить автоматическую проверку стиля в своей среде разработки. Об этом поговорим в следующих статьях.