README.md

phpcf

Форматер был создан для того, чтобы в основном менять пробельные символы: переносы строк, отступы, пробелы вокруг операторов, и т.д. Таким образом, phpcf не заменяет другие схожие утилиты, такие как вышеупомянутый PHP Code Sniffer и PHP Coding Standards Fixer (http://cs.sensiolabs.org) от Фабьена Потенцьера. Он дополняет их, выполняя «грязную работу» по правильной расстановке пробелов и переносов строк в файле. Важно отметить, что наша утилита учитывает изначальное форматирование в файле и меняет только те пробелы, которые не соответствуют выбранному стандарту (в отличие от некоторых других решений, которые сначала удаляют все пробельные токены, а потом начинают форматирование).

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

Пример использования (команда “phpcf apply ” форматирует указанный файл, а “phpcf check ” проверяет форматирование и возвращает ненулевой exit-код в случае наличия неотформатированных фрагментов):

$ cat minifier.php
<?php
$tokens=token_get_all(file_get_contents($argv[1]));$contents='';foreach($tokens as $tok){if($tok[0]===T_WHITESPACE||$tok[0]===T_COMMENT)continue;if($tok[0]===T_AS||$tok[0]===T_ELSE)$contents.=' '.$tok[1].' '; else $contents.=is_array($tok)?$tok[1]:$tok;}echo$contents."\n";

$ phpcf apply minifier.php
minifier.php formatted successfully

$ cat minifier.php
<?php
$tokens = token_get_all(file_get_contents($argv[1]));
$contents = '';
foreach ($tokens as $tok) {
    if ($tok[0] === T_WHITESPACE || $tok[0] === T_COMMENT) continue;
    if ($tok[0] === T_AS || $tok[0] === T_ELSE) $contents .= ' ' . $tok[1] . ' ';
    else $contents .= is_array($tok) ? $tok[1] : $tok;
}
echo $contents . "\n";

$ phpcf check minifier.php; echo $?
minifier.php does not need formatting
0

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

$ cat zebra.php 
<?php
echo "White "."strip".PHP_EOL;
echo "Black "."strip".PHP_EOL; // not formatted
echo "Arse".PHP_EOL;

$ phpcf apply zebra.php:1-2,4
zebra.php formatted successfully

$ cat zebra.php 
<?php
echo "White " . "strip" . PHP_EOL;
echo "Black "."strip".PHP_EOL; // not formatted
echo "Arse" . PHP_EOL;

$ phpcf check zebra.php
zebra.php issues:
        Expected one space before binary operators (= < > * . etc)   on line 3 column 14
        Expected one space after binary operators (= < > * . etc)   on line 3 column 15
        ...

$ echo $?
1

Даже несмотря на то, что утилита написана на PHP, форматирование большинства файлов проходит за доли секунды. Но у нас большой репозиторий и много кода, так что мы написали расширение, которое, будучи подключенным, увеличивает производительность работы в сотню раз: весь наш репозиторий в 2 миллиона строк форматируется за 8 секунд на «ноутбучном» Core i7. Для использования расширения требуется его собрать из директории “ext/”, установить, включить “enable_dl = On” в php.ini или прописать его как extension.

Хотелось бы еще раз подчеркнуть, что phpcf прежде всего меняет пробельные символы и умеет делать лишь простейшие преобразования над кодом: например, заменять короткий открывающий тег на длинный или убирать последний закрывающий тег из файла. Помимо этого, phpcf умеет автоматически исправлять кириллицу в названиях функций на английские символы. Также не трогаются выражения, выровненные вручную с помощью пробелов. Это происходит из-за архитектуры — форматер работает как конечный автомат с правилами, которые задает пользователь, а не как набор «захардкоженных» замен (форматер поставляется с «конфигом по умолчанию», соответствующим нашим правилам форматирования). Поэтому, если вы хотите автоматическую замену “var” на “public” или похожих вещей, рекомендуем обратить внимание на PHP-CS-Fixer — он мало внимания уделяет пробельным символам (в отличие от phpcf), но зато умеет переписывать токены.