Php cs fixer windows

Автоформатирование кода: PHP CodeSniffer и PHP CS Fixer

Отсутствие форматирования — первый признак того, что перед вами код, очень сомнительного качества. А уровень квалификации людей, писавших такой код, далёк даже до джуниора. Однако реальная жизнь вносит свои коррективы, и если уж Вам «прилетел» проект с таким чудо-кодом, в первую очередь надо привести форматирование в порядок, а также позаботиться о том, чтобы подобное больше не попадало в репозиторий. Поэтому тема разговора — PHP CodeSniffer, PHP CS Fixer и git pre-commit хук.

На laracasts есть замечательное видео по этой теме в контексте PhpStorm, здесь же пойдёт речь о том, чего не рассказывал в том видео Джефри (ну а если хотите настроить фиксер под Sublime, смотрите эту статью).

PHP CodeSniffer

Давайте начнём с PHP CodeSniffer. Этот инструмент поможет выявить нарушения форматирования, при надлежащей настройке PhpStorm будет вас об этом информировать путём выделения проблемных частей кода. Кроме всего прочего мы можем воспользоваться консолью для вывода информации об ошибках.

Установка

Лично моя рекомендация — устанавливать пакет не глобально, а на каждом проекте в качестве зависимости по той простой причине, что мы не можем быть уверены, установлен ли инструмент на машине каждого разработчика. Для этого выполняем команду:

Используемый стандарт

Прежде чем двигаться дальше — обязательно согласуйте стандарт с командой:

• если решение зависит от Вас — объясните всем, какого стандарта следует придерживаться, и есть ли какие-либо дополнительные правила (например, обязательная пустая строка перед оператором return )
• если Вы не тим-лид — согласуйте с ним настройки (вообще-то это его работа, но не всегда всё идеально)
• если Вы работаете в интернациональной команде — опять-таки, первое, что нужно сделать — согласовать стандарт с девелоперами «на том конце провода»

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

Можно каждый раз в консоли руками пописывать какие-то дополнительные правила или условия, указывать стандарт и т.д. Но, мы же понимаем, что это не оптимальный вариант. Поэтому, в корне проекта создадим файл phpcs.xml и добавим туда следующее (в качестве примера использую код из текущего проекта):

Пояснения:

• как видите мы также подключаем правила форматирования PEAR, но поскольку нужные не все, мы указываем какие из них следует исключить.
• также мы исключаем некоторые из правил PSR1 и Generic (которые в себя включает PSR2).
• никогда не следует проверять директории node_modules и vendor , поскольку нет гарантии, что разработчики пакетов, придерживаются того же стандарта, что и Вы, даже если речь идёт о конкретном стандарте без всяких дополнительных правил и исключений. Кроме того, не проверяйте директории, где будут размещаться кэшированные файлы. Поскольку данный проект написан на Laravel, я поступил проще и не исключил что-либо, а указал, что нужно проверять только те директории, в которых будет «жить» наш исходный код, а именно: app , database , routes , tests

Следующий шаг — объяснить снифферу, где смотреть правила. Откроем composer.json и в разделе scripts пропишем, что по умолчанию нужно использовать кастомный стандарт, и дабы вывод ошибок сделать более наглядным, следует использовать цвета. Помимо этого, также следует выполнять скрипт после установки и обновления зависимостей — если кто-то/что-то изменит используемый по умолчанию стандарт, я хочу его снова установить:

Основные команды

Пояснение: ниже я намеренно пишу vendor/bin/phpcs , чтобы акцентировать внимание на том, что пакет установлен в проекте. Если же CodeSniffer установлен глобально, используйте просто phpcs

Вывести список установленных стандартов:

Вывести список снифов, используемых в конкретном стандарте:

Проверить форматирование файла file.php :

Проверить весь проект :

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

Вывести код-репорт, т.е. отчёт со сниппетами кода, где были обнаружены ошибки:

Есть ещё и другие команды, но, по моему мнению, вполне хватает перечисленных. Справедливости ради стоит отметить, что PHP CoedSniffer также включает и code beautifier fixer, т.е. можно исправить ошибки (читай отформатировать) командой:

но я всё же предпочитаю php-cs-fixer

PHP CS Fixer

Установка

Опять-таки подумайте устанвливать интсрумент глобально, или для каждого проекта. Второй вариант:

Если выбираете глобальную установку, убедитесь, что в переменную PATH добавлен путь к бинарным файлам composer-a. Проверьте это командой:

Если путь отсутствует — добавьте. Эти действия зависят от платформы. В моём случае (Ubuntu 18.04) необходимо было открыть файл .bashrc находящийся домашнем каталоге /home/ и дописать в конце файла:

Пользовательские правила

Предполагаю, что стандарт уже согласован. В корне проекта создаём файл .php_cs.dist и добавляем следующий код (опять-таки беру код из моего текущего проекта):

Обратите внимание, что помимо стандарта PSR2 также указаны некие дополнительные правила, которые будет применены во время форматирования. Например, удаление бесполезных импортов, бесполезных операторов else и return , сортировка phpdoc блоков и разделение их на группы, удаление лишних пустых строк и т.д. Все доступные инструкции описаны в документации — очень советую посвятить одни выходные изучению возможностей фиксера и просто поэкспериментировать.

Автоформат

В отличие от CodeSniffer-а фиксеру не надо объяснять где брать конфигурацию — он сам просмотрит текущий каталог на предмет наличия необходимого файла, и, если таковой имеется, инструмент его подхватит. Выполнить автоформативароние:

Если не указано иного, php-cs-fixer будет создавать файл с кэшем .php_cs.cache — сразу добавьте название этого файла в .gitignore

Основные команды

Вывести список команд:

Вывести описание правил входящих в конкретный стандарт:

И, как уже был сказано, отформатировать (для разнообразия укажем стандарт Symfony):

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

Git pre-commit hook

Всё это замечательно, но не будет иметь никакого смысла, если вся команда не будет следовать установленным правилам. Решение — не пропускать коммиты с не отформатированными кодом. Для этого поспользуемся перехватчиками Git. В корне проекта создадим файл pre-commit.sh и скопируем в него следующее:

Вообще-то хуки гит-а должны размещаться в директории projects/.git/hooks , но дело в том, что директории .git нет в удалённом репозитории — она созадётся на локальной машине только после инициализации гита или клонирования проекта. Т.е. каким-то образом надо положить этот хук на локальных машинах других разработчиков и изменить права, позволив файлу выполняться. И опять на помощь приходит composer.json . Создадим соответствующий скрипт, и попросим выполнять его после каждой инсталяции или апдейта. Вместе с предыдущим кодом раздел scripts файла composer.json будет выглядеть так:

Подведём итоги. Мы используем:

• PHP CodeSniffer для вывода информации об ошибках форматирования
• PHP CS Fixer для автоформатирования и исправления ошибок
• Git pre-commit хук для предотвращения попадания неотформатированного кода в репозиторий путём отклонения коммитов

Внимание: php-cs-fixer исправит только те ошибки, которые он может исправить, не более. Например, если у Вас не написан phpdoc, fixer за вас его не напишет. Помните об этом.

PHP CS Fixer

In addition to built-in coding assistance, PhpStorm provides checking the source code through integration with the PHP CS Fixer tool, which detects coding standards problems in your code.

To use PHP CS Fixer from PhpStorm instead of command line, you need to register it in PhpStorm and configure it as a PhpStorm code inspection. Once installed and enabled in PhpStorm, the tool is available in any opened PHP file, and no additional steps are required to launch it. The on-the-fly code check is activated upon every update in the file thus making it easy to get rid of discovered problems.

Errors and warnings reported by PHP CS Fixer on-the-fly are displayed as popup messages. When the tool is run in the batch mode, the errors and warnings are displayed in the Inspection Results tool window. Each message has the PHP CS Fixer prefix to distinguish it from PhpStorm internal inspections.

You can have predefined rules applied or define your own custom set of rules.

Prerequisites

Prior to integrating PHP CS Fixer in PhpStorm, make sure the following prerequisites are met:

You are working with PHP CS Fixer version 2.8.0 and later.

The directory containing the PHP engine executable must be added to the system path . This allows code quality tool scripts execute calls to the system-wide PHP engine.

For Docker Compose-based remote interpreters, make sure to use exec mode to avoid spawning additional containers.

In the Settings/Preferences dialog Ctrl+Alt+S , go to PHP .

On the PHP page that opens, click next to the CLI Interpreter list.

In the CLI Interpreters dialog that opens, set the Lifecycle mode for the selected interpreter to Connect to existing container (‘docker-compose exec’) .

Install and configure PHP CS Fixer

PHP CS Fixer scripts can be used as local scripts, the scripts associated with PHP interpreters, or scripts declared as project dependencies and installed via Composer, which is the preferable and recommended way.

Install PHP CS Fixer with Composer

Before you start, make sure Composer is installed on your machine and initialized in the current project as described in Composer dependency manager.

When you install PHP CS Fixer with Composer, PhpStorm automatically downloads the necessary scripts, registers them in the IDE, and, optionally, enables and configures the corresponding code inspection.

Inside composer.json , add the friendsofphp/php-cs-fixer dependency record to the require or require-dev section. Press Ctrl+Space to get code completion for the package name and version.

Do one of the following:

Click the Install shortcut link on top of the editor panel.

If the Non-installed Composer packages inspection is enabled, PhpStorm will highlight the declared dependencies that are not currently installed. Press Alt+Enter and select whether you want to install a specific dependency or all dependencies at once.

Click next to the package record in the composer.json editor gutter to jump to the corresponding Settings/Preferences page and configure PHP CS Fixer manually.

Reset PHP CS Fixer configuration

After PHP CS Fixer is initially configured, further modifications in composer.json will not affect the inspection configuration. To apply newer changes, reset the PHP CS Fixer configuration.

In the Settings/Preferences dialog Ctrl+Alt+S , navigate to PHP | Quality Tools .

On the Quality Tools page that opens, expand the PHP CS Fixer area and click next to the Configuration list.

In the PHP CS Fixer dialog that opens, empty the PHP CS Fixer path field.

Update the project Composer dependencies by clicking Update on top of the composer.json editor panel. See Update dependencies for details.

PhpStorm will perform the PHP CS Fixer configuration anew and thus apply the changes in composer.json .

Configure PHP CS Fixer manually

You can use the manually downloaded local PHP code quality tool scripts or scripts associated with PHP interpreters. There can be a number of local and remote PHP interpreters, the one specified on the PHP page of the Settings/Preferences dialog is considered Project Default . Learn more about configuring PHP interpreters in Configure remote PHP interpreters or in Configure local PHP interpreters.

Choose a PHP CS Fixer script to use

In the Settings/Preferences dialog Ctrl+Alt+S , navigate to PHP | Quality Tools .

On the Quality Tools page that opens, expand the PHP CS Fixer area. From the Configuration list, choose the PHP CS Fixer script:

To use the script associated with a specific remote PHP interpreter, choose the name of this interpreter.

To use a local script, choose Local . In this case the local PHP CS Fixer will be executed no matter which PHP interpreter — local or remote — is used in the project. Note that there can be only one Local configuration for PHP CS Fixer because PhpStorm runs a script ( php-cs-fixer.bat for Windows or php-cs-fixer for Linux and macOS) that contains a path to a PHP engine.

To use the script associated with the default project interpreter, that is, the one chosen on the PHP page of the Settings/Preferences dialog, choose By default project interpreter .

Configure a local PHP CS Fixer script

Download and install the PHP CS Fixer scripts.

To check the PHP CS Fixer installation, switch to the installation directory and run the following command:

If the tool is available, you will get a message in the following format:

To have code checked against your own custom coding standard, create it. Store the rules and the .php_cs or php_cs.dist file that points to them in the rulesets root directory.

Register the local PHP CS Fixer script in PhpStorm:

In the Settings/Preferences dialog Ctrl+Alt+S , navigate to PHP | Quality Tools .

On the Quality Tools page that opens, expand the PHP CS Fixer area and click next to the Configuration list.

In the PHP CS Fixer dialog that opens, specify the location of the php-cs-fixer.bat or php-cs-fixer PHP CS Fixer executable in the PHP CS Fixer path field. Type the path manually or click and select the relevant folder in the dialog that opens.

To check that the specified path to php-cs-fixer.bat or php-cs-fixer ensures interaction between PhpStorm and PHP CS Fixer, that is, the tool can be launched from PhpStorm and PhpStorm will receive problem reports from it, click the Validate button. This validation is equal to running the php-cs-fixer —version command. If validation passes successfully, PhpStorm displays the information on the detected PHP CS Fixer version.

If necessary, in the Tool process timeout field, specify how long you want PhpStorm to wait for a result from PHP CS Fixer, whereupon the process is terminated to prevent excessive CPU and memory usage.

Configure a PHP CS Fixer script associated with a PHP interpreter

In the Settings/Preferences dialog Ctrl+Alt+S , navigate to PHP | Quality Tools .

On the Quality Tools page that opens, expand the PHP CS Fixer area and click next to the Configuration list. The PHP CS Fixer dialog opens showing the list of all the configured PHP CS Fixer scripts in the left-hand pane, one of them is of the type Local and others are named after the PHP interpreters with which the scripts are associated.

Click on the toolbar. In the PHP CS Fixer by Remote Interpreter dialog that opens, choose the remote PHP interpreter to use the associated script from. If the list does not contain a relevant interpreter, click and configure a remote interpreter in the CLI Interpreters dialog as described in Configure remote PHP interpreters.

When you click OK , PhpStorm brings you back to the PHP CS Fixer dialog where the new PHP CS Fixer configuration is added to the list and the right-hand pane shows the chosen remote PHP interpreter, the path to the PHP CS Fixer associated with it, and the advanced PHP CS Fixer options.

If necessary, in the Tool process timeout field, specify how long you want PhpStorm to wait for a result from PHP CS Fixer, whereupon the process is terminated to prevent excessive CPU and memory usage.

Configure PHP CS Fixer as a PhpStorm inspection

Configure the PHP CS Fixer inspection with Composer

You can include the information on the default and custom PHP CS Fixer rulesets inside the scripts section of composer.json . When you install or update project dependencies, the specified rulesets will be detected and the PHP CS Fixer validation inspection will be enabled automatically.

If no ruleset is specified in the scripts section of composer.json , PhpStorm will additionally check the project root to locate the ruleset with the .php_cs or .php_cs.dist default name. If the file is present, it will be automatically selected as the inspection’s Custom ruleset.

In the scripts section of composer.json , add the php-cs-fixer PHP CS Fixer launch command into one of the leaf elements.

Provide the —rules argument to denote the coding standard used. For example, adding the following record will set the coding standard to PSR1 :

Alternatively, provide the —config argument and the path to the ruleset file, which will set the coding standard to Custom :

After PHP CS Fixer is initially configured, further modifications in composer.json will not affect the inspection configuration. To apply newer changes, reset the PHP CS Fixer configuration on the PHP | Quality Tools page of the Settings/Preferences dialog Ctrl+Alt+S and update project dependencies.

Configure the PHP CS Fixer inspection manually

In the Settings/Preferences dialog Ctrl+Alt+S , click Inspections under Editor .

On the Inspections page that opens, expand the PHP | Quality Tools node and select the checkbox next to PHP CS Fixer validation .

If you have installed PHP CS Fixer with Composer but the corresponding inspection is currently disabled, PhpStorm highlights its record in composer.json . Press Alt+Enter and use the provided Enable inspection quick-fix to enable the inspection and open the Inspections page.

On the right-hand pane of the page, configure the PHP CS Fixer tool using the controls in the Options area:

From the Severity list, choose the severity degree for the PHP CS Fixer inspection. The selected value determines how serious the detected discrepancies will be treated by PhpStorm and presented in the inspection results.

From the Scope list, choose the scope to limit the inspection application to.

To allow risky rules, that is, the rules that can change code behavior, select the Allow risky rules for built-in rulesets checkbox. By default, risky rules are not allowed.

Appoint the coding standard to apply.

To use one of the predefined coding standards, select it the Coding standard list, appoint the coding style to check your code against. The list contains all the coding standards declared inside the main php-cs-fixer directory structure.

To have your code checked against your own previously defined coding standard, choose Custom . Click Browse and in the Custom Coding Standard dialog that opens, specify the path to the .php_cs or .php_cs.dist file for your own coding standard in the Path to ruleset field. Type the path manually or click Browse and choose the relevant folder in the dialog that opens.

Share a custom coding style with the team

Put the root directory of your coding standard under the project root.

Make sure that a project profile is selected at the top of the Inspections page. Such profiles are saved in a particular project’s .idea directory (for example, $PROJECT_DIR$/.idea/inspectionProfiles ). See Configure profiles for details.

On the Version Control page of the Settings/Preferences dialog, make sure that the .idea directory is put under version control.

Run PHP CS Fixer in the batch mode

From the main menu, select Code | Inspect code .

Select the inspection profile from the list, or click to configure a new profile in the Inspections dialog that opens. You can also click to check, which fixes will be applied and make sure that the PHP CS Fixer validation inspection is enabled.

View the inspection results in the Inspection results tool window. Errors and warnings reported by PHP CS Fixer are prefixed with PHP CS Fixer to distinguish them from PhpStorm internal inspections.

Exclude files from PHP CS Fixer inspection

When waiting for PHP CS Fixer response exceeds the limit specified in the Tool process timeout field in the PHP CS Fixer dialog, PhpStorm suggests adding the file to the ignore list .

In the Settings/Preferences dialog Ctrl+Alt+S , navigate to PHP | Quality Tools .

On the Quality Tools page that opens, expand the PHP CS Fixer area and click the Show ignored files link.

To add a file, click and locate the desired file in the dialog that opens.

To delete a file from the list and have PHP CS Fixer process it again, select the file and click .

To remove all the files from the list, click .