PHPプロジェクトを静的解析するためのGitLab CIパイプラインの作成方法
コードに対してスタティック分析を実行することで、隠れた問題を見つけて時間を節約できます。PHPStanはPHPのためのスタティック分析ツールで、コードベースの品質を向上させる手助けをします。GitLab CIパイプライン内でPHPStanを実行する方法は次の通りです。
新しい機能を開発している間、PHPStanを定期的に実行するのは良いことです。ただし、ローカルで実行するだけでは限界があります。他のチームメンバーがあなたと同様に規律を守っていることに依存しています。静的解析をCI/CDワークフローに統合することで、プロジェクトのメインブランチを壊すようなコードはマージできなくなります。
PHPStanの設定方法
まず、プロジェクトにPHPStanを追加する必要があります。PHPStanのインストールと設定に関する詳細なガイドはすでに用意していますので、ここでは基本的な部分だけを説明します。
まず、Composerを使ってPHPStanをインストールします。
composer require --dev phpstan/phpstan次に、プロジェクトに基本的な phpstan.neon 設定ファイルを作成します:
parameters:
level: max
paths:
- src
- tests
tmpDir: .tmp
一時ディレクトリはGitLab CIのキャッシュを支援するために上書きされ、下記の設定が行われます。
これで、PHPStanをローカルで実行して設定が機能しているかを確認できます。
vendor/bin/phpstan analyseこの段階では、テストが通るかどうかは関係ありません。
CIのためのGitLabの設定
自分のコードをGitLabサーバーのプロジェクトにプッシュしたことを確認してください。プロジェクトのパイプライン機能が有効になっているか確認する必要があります。左のサイドバーに「CI/CD」が表示されていれば、問題ありません。
プロジェクトのCIシステムを有効にするには、サイドバーの「設定」ボタンをクリックしてください。「可視性、プロジェクトの機能、権限」のセクションを展開し、「パイプライン」機能を有効にします。
GitLabのマージリクエスト（MR）を規律正しく使用する場合、成功したパイプラインがなければMRがマージされないようにGitLabを設定することができます。「マージリクエスト」設定セクションを展開し、「パイプラインは成功しなければならない」のトグルボタンをチェックします。「保存」をクリックして確認します。これにより、PHPStanが変更に対して失敗した場合にMRを誤ってマージすることを防ぐことができます。
GitLab CIを使用するには、インスタンス、グループ、またはプロジェクトレベルで定義されたGitLab Runnerが必要です。Runnerは、GitLabシステムによって作成されたCIジョブを実行する責任があります。
私たちは、CIパイプラインでPHPStanを実行するためにPHPStan Dockerイメージを使用します。これには、Dockerエグゼキュータを使用するGitLab Runnerの設定が必要です。セルフマネージドインスタンスを使用している場合は、新しいRunnerを構成する必要がある場合、GitLab CIの設定に関する記事のガイダンスに従ってください。
GitLab CI パイプラインの作成
GitLab CIは、プロジェクトのルートにある.gitlab-ci.ymlファイルを使用して構成されています。CIパイプラインは、複数の順次ステージをサポートしています。各ステージのジョブは並行して実行されます。PHPStanを実行する目的のために、1つのジョブを実行する単一のステージが必要です。
stages:
- phpstan
cache:
key: $CI_COMMIT_REF_SLUG
paths:
- .tmp/
- vendor/
phpstan:
stage: phpstan
image: ghcr.io/phpstan/phpstan
script:
- analyse --no-progress --error-format gitlab > phpstan.json
artifacts:
when: always
reports:
codequality: phpstan.json
このGitLab CIファイルには、私たちのパイプライン内でPHPStanを実行するために必要なすべてが含まれています。私たちは、phpstanというステージを定義し、その中にphpstanとも呼ばれるジョブを含めています。このジョブは、GitHubコンテナレジストリからの公式PHPStan Dockerイメージを使用します。
GitLab CIキャッシュは、.tmpおよびvendorディレクトリをキャッシュするように設定されています。これにより、同じブランチでの後続の実行のパフォーマンスが向上します。キャッシュは自動的に復元されます。私たちのphpstan.neonに戻ると、tmpDirを.tmpに設定しているのはこの理由からです - これにより、CIパイプラインのキャッシング設定で自信を持って参照できるようになります。
私たちは、各実行で無駄にComposerの依存関係を再インストールする必要がないように、vendorをキャッシュします。手動でcomposer installを実行する必要はないことに注意してください - 公式のPHPStan Dockerイメージはそれを自動的に呼び出します。
--error-format フラグは PHPStan の analyse コマンドに渡されます。これにより PHPStan は GitLab のコード品質レポートが受け入れる形式の JSON ファイルを作成します。artifacts セクションの下では、このファイルがジョブ完了後に GitLab にアップロードされます。
パイプラインを使用して
.gitlab-ci.yml をコミットして、GitLab サーバーにプッシュしてください。CI システムが動作を開始し、最初のパイプラインが作成されるはずです。左側のナビゲーションにある "CI/CD" リンクを使用して、パイプラインの進行状況を確認してください。
緑のチェックマークが表示されたら、PHPStanのテストが合格したということです！あなたのブランチは良好な状態で、マージする準備ができています。赤いバツ印が表示される場合は、まだ作業が残っています。PHPStanとGitLab CIは、潜在的に壊れたコードのマージを防ぎました。
パイプラインの右側にあるダウンロードアイコンをクリックすることで、エラーのリストを取得できます。PHPStanが見つけたエラーのJSONレポートを取得するには、PHPStanコード品質アーティファクトを選択してください。
マージリクエストとの併用
JSONを手動で読むのはあまり良い体験ではありません。しかし、GitLabのマージリクエストは報告書の内容を自動的に表示します。報告書はGitLabのコード品質アーティファクトとしてタグ付けされているため、GitLabはその情報をどのように表示するかを知っています。
パイプラインが失敗しているマージリクエストには、展開可能な「コード品質」セクションが表示されるべきです。これは、遭遇したエラーの数を示します。そのセクションを展開して、PHPStanによって見つかった問題の完全なリストを表示してください。
問題に対処したら、変更をGitLabにプッシュしてください。パイプラインが再度実行されます。完了すると、パイプライン画面とマージリクエストのコード品質ウィジェットに新しいステータスが表示されます。
結論
PHPStanは、隠れた問題に対して影響を受けにくいより良いPHPを書く手助けをします。それを最大限に活用するためには、このツールを開発ワークフローに組み込み、無視したり回避したりできないようにする必要があります。
PHPStanをGitLab CIと共に使用することで、コードに自信を持てるために必要な一貫性が得られます。パイプラインが失敗したMRをブロックするようにGitLabを設定することで、PHPStanの実行を通過しない限り、変更がメインブランチに入ることはなくなります。PHPStanはGitLabのコード品質レポートを完全にサポートしているため、Web UIを離れることなくエラーを評価することが容易になり、発見される問題を迅速に修正するのに役立ちます。