Phinderとは
プルリクエストのソース差分から特定の文字列を見つけ出してくれるLintツールです。
独自のルールを追加することで、非推奨の記述や小さなミスの発見を自動化することができます。
導入方法
①以下のコマンドを打つ（php7.0↑Composerが使える環境）
$ composer require --dev sider/phinder
$ vendor/bin/phinder -v
②phinder.ymlというファイル名でルールを記述
”pattern”と”message”のセットでルールを記述します。
例
- id: in_array_without_3rd_param
pattern: in_array(_, _)
message: Specify the 3rd parameter explicitly when calling `in_array` to avoid unexpected comparison results.
③phinderのコマンドを打つ
$ vendor/bin/phinder find
実行例
Phinder ページ本文和訳
英語では読みにくい方のためにざっくり本文を和訳しました。
原文(https://packagist.org/packages/tomokinakamaru/phinder)
PhinderはPHP記述のパーツを見つけるツールです。このツールは、静的なバグ検出ではなく、主にコードレビュープロセスの高速化を目的としています。
プロジェクトに次のローカルルールがあるとします。
予期しない比較結果を避けるため、in_arrayを呼び出す際3番目のパラメーターを明示的に指定します。
コードレビューでチェックすれば、コードはこのルールに従います。しかし、それをチェックするのを忘れたら？プロジェクトに多数のルールがある場合は？おそらく、そのような低レベルのチェックは機械にやらせたいと思うことでしょう。
Phinderは、このような低レベルのものを自動的にチェックするためのコマンドラインツールです。以下のymlをphinder.ymlとして保存し、ターミナルからphinderを実行すると、Phinderが違反を発見します。
- id: in_array_without_3rd_param
pattern: in_array(_, _)
message: Specify the 3rd parameter explicitly when calling `in_array` to avoid unexpected comparison results.
インストール
Phinderの要求はPHP >= 7.0です。Composerを使ってインストールできます。
composer require --dev sider/phinder
vendor/bin/phinder -v
Dockerを使う場合
docker run --rm -t -v $(pwd):/workdir sider/phinder
クイックスタート
最初に、phinder initコマンドを入力しphinder.ymlの例を作成しましょう。
$ phinder init
`phinder.yml` has been created successfully
$ cat phinder.yaml
# Feel free to add your own project rules to this YAML file.
# The following example describes the rule syntax.
# See the documentation for more details: https://github.com/sider/phinder/tree/master/doc
- # The rule identifier. It must be unique in the YAML file.
id: sample.var_dump
# Pattern syntax. The `...` pattern matches variable length arguments or array pairs.
# As a result, this pattern matches `var_dump` function call with any arguments.
pattern: var_dump(...)
# The message to display when code pieces are matched with the pattern.
message: Do not use var_dump.
# Exceptions that can ignore this violation.
justification: Allowed when debugging
- id: sample.in_array_without_3rd_param
# `_` pattern mattches any single expression.
# This means the pattern always matches `in_array` function call with any two arguments.
pattern: in_array(_, _)
message: Specify 3rd parameter explicitly when calling in_array to avoid unexpected comparison results.
# You can test whether your pattern works as expected with `phinder test`.
test:
# Code pieces that will match your pattern.
# This means the following codes are bad as you expected.
fail:
- in_array(1, $arr)
- in_array(2, $arr)
# Code pieces that will NOT match your pattern.
# This means the following codes are good as you expected.
pass:
- in_array(3, $arr, true)
- in_array(4, $arr, false)
次に、phinderコマンドを実行して、あなたのコードに対してパターンを適用できます。
$ phinder
パターンがコードにどのように一致するかを理解したら、実際のプロジェクトに役立つルールを追加しましょう。可能性は無限です！
ドキュメント
・サンプルルールとその説明
https://github.com/tomokinakamaru/phinder/blob/HEAD/doc/rule.md
・パターン構文
https://github.com/tomokinakamaru/phinder/blob/HEAD/doc/pattern-syntax.md
・コマンドラインオプション
https://github.com/tomokinakamaru/phinder/blob/HEAD/doc/command-line-options.md
寄稿
バグレポート、機能リクエスト、プルリクエストは、GitHub（https://github.com/sider/phinder）にて歓迎しています。
謝辞
Phinderは、Querly、ast-grep、およびASTsearchに触発されています。実装は、PHP-Parserとkmyacc-forkedに大きく依存しています。
おわりに
今回試したのはローカルで実行する方法ですが、Sider（https://sider.review/ja）
と組み合わせてGUI上で確認する運用が一般的なようです。
参考：
https://blog-ja.sideci.com/entry/2019/01/16/144242
https://packagist.org/packages/tomokinakamaru/phinder
https://yourmystar-engineer.hatenablog.jp/entry/2018/10/02/121334