🎉 🛰️ 🛃 Badoo PHP Code Formatter。オープンソースになりました！ 👩‍❤️‍💋‍👨 😢 🕢

数年前、Badooは従業員数が20人から100人以上に大幅に増加し始めました。これには、多くの開発プロセスの大幅な見直しが必要でした。私たちが遭遇した問題の1つは、すべての開発者が単一のコーディング標準に従うようにして、すべてのコードが一貫性があり、簡単に保守できるようにする方法です。

この問題を解決するために、次のことができるコードフォーマットツールを実装することにしました。

ファイル自体に触れることなく、リストの形式でフォーマット標準の非準拠に関するメッセージを表示します。
見つかったすべてのフォーマットの問題を自動的に修正します。
ファイルの一部のみをフォーマットできます（履歴を失わないように、リポジトリ全体をすぐに再フォーマットする必要はありません）。

このようなツールを作成するための基礎となる2つのプロジェクト、PHP BeautifierとPHP Code Snifferを検討しました。 1つ目はコードをフォーマットできましたが、診断を印刷できませんでした。2つ目は、反対に、診断を印刷できましたが、ファイルをフォーマットできませんでした。残念ながら、これらのプロジェクトは両方とも、私たちの推定では、それらに欠けていた機能を追加するのにあまり適していないため、新しいユーティリティ-phpcf（PHP Code Formatter）が作成されました。過去2年間、git pre-receiveフックとして機能しており、コーディング標準に従ってフォーマットされていない変更を拒否（！）するように構成されています。

最後に、ユーティリティのソースコードを一般公開します： github.com/badoo/phpcf

機能性

フォーマッタは、基本的に空白を変更するために作成されました：改行、インデント、演算子の周りのスペースなど。したがって、phpcfは、前述のPHP Code SnifferやFabien PotencierのPHP Coding Standards Fixerなどの他の同様のユーティリティを置き換えません。それはそれらを補完し、ファイル内のスペースと改行の正しい配置で「汚い作業」を実行します。ユーティリティがファイルの初期フォーマットを考慮し、選択した標準に対応しないスペースのみを変更することに注意することが重要です（最初にすべての空白トークンを削除してからフォーマットを開始する他のソリューションとは異なります）。

このユーティリティは拡張可能であり、カスタムスタイルセットをサポートしています。独自のフォーマットスタイルを非常に簡単に定義できます。これにより、当社とは異なる標準が実装されます（当社のコーディング標準はPSRに非常に近い）。

使用例（「phpcf apply <filename>」コマンドは指定されたファイルをフォーマットし、「phpcf check <filename>」はフォーマットをチェックし、未フォーマットのフラグメントがある場合はゼロ以外の終了コードを返します）：

$ 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で記述されていますが、ほとんどのファイルは一瞬でフォーマットされます。しかし、大きなリポジトリと多数のコードがあるため、接続すると生産性が100倍に向上する拡張機能を作成しました。200万行のリポジトリ全体が「ノートブック」Core i7で8秒でフォーマットされます。拡張機能を使用するには、「ext /」ディレクトリから収集し、インストールし、php.iniで「enable_dl = On」を有効にするか、拡張機能として登録する必要があります。

phpcfはまず最初に空白を変更し、コード上で最も単純な変換しかできないことをもう一度強調したいと思います。たとえば、短い開始タグを長いタグに置き換えるか、ファイルから最後の終了タグを削除します。さらに、phpcfは、英語の文字の関数名のキリル文字を自動的に修正できます。また、スペースで手動で配置された式は影響を受けません。これはアーキテクチャーによるものです-フォーマッターは、ハードコードされた置換のセットとしてではなく、ユーザーが設定したルールを持つステートマシンとして機能します（フォーマッターには、フォーマットルールに一致する「デフォルト構成」が付属します）。したがって、「var」を「public」または同様のものに自動的に置き換える場合は、PHP-CS-Fixerに注意することをお勧めします-phpcfとは異なり、空白文字にはほとんど注意を払いませんが、トークンを書き換えることができます。

PHPバージョンのサポート

当初、フォーマッタはPHP 5.3で動作し、それだけをサポートしていました。現時点では、PHP 5.4および5.5の構文を完全にサポートしており、フォーマッターが機能するには、5.4以上のPHPバージョンが必要です。 PHPの以前のバージョン向けのコードをフォーマットする場合は、それを行うことができますが、phpcf自体はPHP 5.4+を使用して起動する必要があります。

phpcfは、たとえば不均衡な括弧を含む「未完成」ファイルをフォーマットできないことに注意してください。この場合、エラーメッセージが表示され、ファイルは単にフォーマットされません。さらに、場合によっては、フォーマッタ自体がファイルの構文をチェックしないため、インタープリターの観点から「無効な」コードをフォーマットできます。

PHPの将来のバージョンのサポートに関して、phpcfアーキテクチャは、ファイルに「なじみのない」キーワードとトークンを追加または会議するとき、それらを単に無視してそのままにするようなものです。したがって、phpcfはすでにPHPの将来のバージョンをサポートしていますが、未知のトークンにはフォーマットルールが適用されないことに注意してください。

Git統合サポート

ユーティリティをダウンロードすると、「チェック」、「プレビュー」、「適用」アクションだけでなく、「-git」サフィックスが付いた同じアクションもあることに気付くでしょう。 Badooでは、バージョン管理システムとしてGitを使用します。デフォルトでは、変更された行のみがチェックおよびフォーマットされます。開発者に変更された行の番号を思い出させないために、次のように機能する「* -git」コマンドを作成しました。

インデックスに追加された「コミットされていない」変更を表示します。
現在のブランチで行われたが、origin / masterおよびorigin / <current-branch>に存在しない変更を表示します（対応するブランチはgit push / git pullで更新されます）。つまり、まだリポジトリに送信されていません。
（1）および（2）にある行にのみ書式設定を適用します。

機能ブランチで開発を使用し、同時にマスターブランチに製品コードがあるため、「-git」コマンドはこのフローに合わせて調整され、上記のアルゴリズムに従って変更された行を決定します。

使用例：

 (master) $ git checkout -b some_feature (some_feature) $ vim test.php #  test.php (some_feature) $ phpcf apply-git #    ,     test.php formatted successfully

phpcfクラスを直接使用する

ユーティリティとしてphpcfを使用することに加えて、拡張機能拡張を含め、phpcfクラスを直接使用することもできます。この機能は、PHPファイルをフォーマットするためのWebサービスを作成するなど、さまざまなタスクに役立ちます。必要に応じて、コードレビュープロセスで使用します。ブランチで行われた変更を表示する場合、フォーマットにのみ関連する変更を表示しない方法はわかりません（このため、ファイルの2つのバージョンは完全にフォーマットされ、古いものと新しいものがあり、その後、それらの間の差分が考慮されます）

phpcfクラスを直接使用する例：

 <?php //     require_once __PHPCF_SRC . '/src/init.php'; //    $Options = new \Phpcf\Options(); //   (    ) $Options->setTabSequence(' '); //  3-4   Tab $Options->setMaxLineLength(130); // 120   $Options->setCustomStyle('style'); //       $Options->toggleCyrillicFilter(true|false); //     $Options->usePure(true); //     extension $Formatter = new \Phpcf\Formatter($Options); //   $Formatter->formatFile('file.php'); //   $Formatter->formatFile('file.php:1-40,65'); //   //   $Formatter->format('<?php phpinfo()'); //     $Formatter->format($code, [1, 2, 10]); //     //       \Phpcf\FormattingResult $Result->getContent(); //     $Result->wasFormatted(); // bool,     $Result->getIssues(); // array,      $Result->getError(); // \Exception|null

PHPStormの例でのIDEとの統合

PHPStormの使用中にフォーマッタを使用してPHPコードをフォーマットできるようにする場合は、次の手順を実行できます。

1.git clone https://github.com/badoo/phpcf.git

2. PHPStormで、設定に移動し、「外部ツール」セクションを見つけます。

3. [追加...]をクリックして、フィールドに入力します。

名前：ファイル全体をフォーマットする

グループ：phpcf

「コンソールを開く」のチェックを外します（邪魔にならないように）

プログラム：php

パラメーター：path_to_phpcf.git / phpcf apply $ FilePath $

作業ディレクトリ：任意

名前：形式の選択

グループ：phpcf

「コンソールを開く」のチェックを外します（邪魔にならないように）

プログラム：php

パラメーター：path_to_phpcf.git / phpcf apply $ FilePath $：$ SelectionStartLine $-$ SelectionEndLine $

作業ディレクトリ：任意

その後、ホットキーを対応するアクションに添付し、ファイル全体または選択したフラグメントのみをフォーマットできます。

さらに、「phpcf check-git --emacs」の操作を同じ方法で設定できます。このモードでは、phpcfはファイル名を行番号とともにemacsスタイルで出力します。これにより、リンクをクリックして出力で指定された行に移動できます。

実装

作業の過程で、フォーマッタは次の手順を実行します。

フォーマットするファイル名と行番号のリストを準備します。
token_get_all（prepareTokens）を呼び出して、ファイルのトークンのリストを取得します。
フックを実行する機能を使用してトークンを単一の形式に変換し、一部のトークンを他のトークンに置き換えることができます。
プロセス（）メソッドの呼び出し。これは、状態マシンPhpcf \ Impl \ Fsmを使用してすべてのトークンを渡し、フォーマットアクション（exec）の配列を構成します。
exec（）メソッドの呼び出し。生成されたアクションの配列が処理され、最終的な文字列に変換されます。

詳細

クラスPhpcf \ Impl \ Fsmの説明-トークンを解析するためのステートマシン

クラスPhpcf \ Impl \ Fsmは、状態がスタック（配列）として表される有限状態マシンです。スタックの一番上の要素は、状態遷移規則に使用されます。

 <?php $fsm_context_rules = array( 'CTX_SOMETHING' => array( //  ,    = CTX_SOMETHING 'T_1' => 'CTX_OTHER_THING', //   T_1     CTX_OTHER_THING 'T_2' => array('CTX_OTHER_THING'), //   T_2  push(CTX_OTHER_THING) 'T_3' => -2, //   T_3  pop()   2  //   N     M     // ,        'T_4' => array(PHPCF_CTX_NOW => N, PHPCF_CTX_NEXT => M), // c        'T_5' => array('REPLACE' => array(-2, array('CTX_OTHER_THING')), //      ,     ,    ), );

一般的に、ステートマシンのルールは次のとおりです。

 <?php $fsm_context_rules = array( '<context_name>[ ... <context_name>]' => array( '<token_code>[ ... <token_code>]' => <context_rule>, ), ); $context_rule = '<context_name>'; //    <context_name>     $context_rule = array('<context_name>'); //    <context_name>,  <context_name>   $context_rule = -N; //   N  , N —   //  ,    PHPCF_CTX_NOW,       , //   PHPCF_CTX_NEXT ( debug        "delayed rule") $context_rule = array(PHPCF_CTX_NOW => <context_rule>, PHPCF_CTX_NEXT => <context_rule>);

フォーマット規則の配列：$コントロール

フォーマッタは基本的に設計されているので、空白トークンの内容のみを制御します（フックを除く）。すべてのフォーマット規則は、$ controls配列で定義され、次の形式で提示されます。

 <?php $controls = array( '<token_code>[ ... <token_code>]' => array( //    ,       ['<context>' => <formatting_rule>,] //  <formatting_rule>    PHPCF_KEY_ALL => <formatting_rule>, //  <formatting_rule>,         ), ); $formatting_rule = array( PHPCF_KEY_DESCR_LEFT => '<description>', //  ,        PHPCF_KEY_LEFT => PHPCF_EX_<action>, // ,         PHPCF_KEY_DESCR_RIGHT => '<description>', //      PHPCF_KEY_RIGHT => PHPCF_EX_<action>, // ,     ); // : 'T_AS T_ELSEIF T_ELSE T_CATCH' => array( //   "as", "elseif", "else"  "catch" PHPCF_KEY_ALL => array( //    PHPCF_KEY_DESCR_LEFT => 'One space before as, elseif, else, catch', PHPCF_KEY_LEFT => PHPCF_EX_SHRINK_SPACES_STRONG, //       ( ) PHPCF_KEY_DESCR_RIGHT => 'One space after as, elseif, else, catch', //    PHPCF_KEY_RIGHT => PHPCF_EX_SHRINK_SPACES_STRONG, //   ) ),

たとえば、「$ a = $ b;」など、同じスペースに対して異なるルールが定義されている場合 "="の後、スペースを1つ入れる必要があり、$ bの前-すべてのスペースを削除します。ルールの適用順序は優先順位によって異なります。操作の優先度については、「PHPCF_EX-constants」セクションで説明しています。ルールが高いほど、優先度が高くなります。

トークンフック

$ token_hook_namesプロパティは、prepareTokensメソッドがこのトークンを検出したときに呼び出す必要があるメソッドの名前を定義します。フックは次のように定義されます。

 <?php namespace Phpcf\Impl; class Pure implements \Phpcf\IFormatter { /* *  $idx_tokens      array(T_SOMETHING => 'T_SOMETHING'), *       * *  $i_value       ,  token_get_all * *           $this->tokens   each() *   : tokenHookStr * *     ,     *        * *   ,      : */ private function tokenHookDoNothing($idx_tokens, $i_value) { if (is_array($i_value)) { $this->current_line = $i_value[2]; return array( array( PHPCF_KEY_CODE => $idx_tokens[$i_value[0]], PHPCF_KEY_TEXT => $i_value[1], PHPCF_KEY_LINE => $this->current_line, ) ); // set correct current line for next token if it does not have line number $this->current_line += substr_count($i_value[1], "\n"); } return array( array( PHPCF_KEY_CODE => $i_value, PHPCF_KEY_TEXT => $i_value, PHPCF_KEY_LINE => $this->current_line, ) ); } }

トークンのフックの説明

トークンのフックの簡単な説明と、フックの出現理由とそのアクションの説明：

tokenHookHeredoc、tokenHookStr：デフォルトでは、PHPはHEREDOC、二重引用符、斜め引用符内のテキストを「トークン化」し、そこで変数を選択します。フォーマッタは行に触れてはならないため、内容は1つのトークンに結合されます。
tokenHookOpenBraceは、括弧内の式が長い（デフォルトでは120文字）か、式で改行が使用されている場合、トークン "（"を "（_LONG"に変換します。「long」配列と「short」配列を区別するために使用され、関数の呼び出しと定義;
tokenHookCheckUnaryは、演算子が単項演算子（たとえば、「+」、「-」、＆）かどうかを判別します。ルール内のコンテキスト間の遷移の数を減らすのに役立ちます。
tokenHookStaticは、「static :: HELLO」のような呼び出しを「public static function」としての使用から分離します。また、状態遷移のロジックを簡素化するのにも役立ちます。
tokenHookClassdefは、キーワードの後に改行（たとえば、「const \ n」）があると判断し、「const \ n var1 = 1、\ n var2 = 2;」などの構造を正しくフォーマットするために使用されることを決定します。
tokenHookOpenTagは、開始タグが長いことを確認し、開始タグから空白も分離します（「<？php \ n」を2つのトークンに変換します：「<？php」と「\ n」）。
tokenHookCloseTagは、ファイルの最後に終了タグがないことを確認します。
tokenHookIncrementは、変数のどちら側が演算子「++」または「-」であるかを決定します。コンテキスト間の遷移のロジックを簡素化するために作られました。
tokenHookWhiteSpaceは、式がスペースで正当化されることを決定し、T_WHITESPACEをT_WHITESPACE_ALIGNEDに置き換えます。T_WHITESPACE_ALIGNEDは、フォーマット時に変更されません。
tokenHookElseは、elseが単一行かブロックを含むかを決定します。ロジックを簡素化するために作られました。
tokenHookCommentは、単一行のコメントが「//」で始まることを確認し、トークンから改行を分離します（「// something \ n」は「// something」と「\ n」になります）。
tokenHookTStringは、このT_STRINGがメソッドまたは関数の名前である場合、T_STRINGの名前をT_FUNCTION_NAMEに変更します。コンテキスト間の遷移のロジックを簡素化するために作られました。
tokenHookBinaryは、ステートメントを次の行に転送する状況を処理するために使用されます。
tokenHookCommaは、長い配列の新しい行にラップできるコンマの場合、「、」を「、_LONG」に変換します。
tokenHookFunctionは、匿名関数と非匿名関数を互いに分離します。

フックがトークンの内容を変更する場合は、これを行う権利があるかどうかを確認する必要があります($can_change_tokens = !isset($this->lines) || isset($this->lines[$this->current_line]))

。そうでない場合、フックはトークンの内容を変更するべきではありませんが、その番号を変更し、トークンをそのコンポーネント部分に分割できます。例はtokenHookOpenTagです。ユーザーがファイルの一部のみをフォーマットするように要求した場合、開始タグの内容はチェックしませんが、開始タグから空白を分離します。開始タグと単一行コメントの後の行数（およびインデント）を正しく考慮するために、空白の分離が必要です。

参照資料

PHP Beautifier-pear.php.net/package/PHP_Beautifier

PHPコードスニファー-pear.php.net/package/PHP_CodeSniffer

PHP CS Fixer-github.com/fabpot/PHP-CS-Fixer

phpcfユーティリティ-github.com/badoo/phpcf

私たちの記事を読んでくれてありがとう、私たちはあなたの提案やコメントを聞く準備ができています。このユーティリティの使用をお楽しみください。

Yuri youROCK Nasretdinov、PHP開発者Badoo

Alexander Alexkrash Krasheninnikov 、PHP開発者Badoo

Badoo PHP Code Formatter。 オープンソースになりました！

機能性