2025.02.07 セキュリティ

PsalmとPHPStanの比較：機能や使用感の違いを検証

目次

Psalmとは何か？PHP静的解析ツールの概要と特徴

Psalm（PHP Static Analysis Made Easy）は、Facebookが開発したPHP用の静的解析ツールです。
静的解析とは、コードを実行せずにエラーや型の不整合を検出する技術であり、コードの品質向上やバグの早期発見に役立ちます。
Psalmは、PHPの型情報を解析し、コード内の潜在的なバグや不要なコードを発見するのに優れた機能を提供します。
Psalmを利用することで、型のミスや未定義変数の使用、不要な関数呼び出しなどの問題を早期に発見できます。
また、PHPのDocBlockアノテーションを活用し、より詳細な型チェックが可能です。
他の静的解析ツール（PHPStanなど）と比較して、Psalmは型の厳密なチェック機能が充実しており、大規模なPHPプロジェクトにも適用しやすい特徴を持っています。
Psalmはオープンソースであり、Composerを使用して簡単にインストールできます。
設定ファイル（`psalm.xml`）を作成することで、解析レベルや対象のファイルをカスタマイズできるため、プロジェクトごとに最適な設定を適用できます。
さらに、プラグイン機能を活用することで、カスタムルールの追加や拡張も可能です。

Psalmの基本概念と静的解析の役割

静的解析とは、コードを実行せずに解析を行い、構文エラーや論理的なミスを検出する手法です。
Psalmはこの静的解析をPHPのコードに適用し、型チェックや未定義変数の検出、関数の戻り値の整合性チェックなどを行います。
一般的なPHP開発では、実行時にエラーが発生することが多く、それをデバッグするのに時間がかかります。
しかし、Psalmを使用すれば、コードの実行前に問題を発見できるため、バグの発生を未然に防ぐことができます。

Psalmが提供する主な機能とその利点

Psalmは、PHPのコード解析を強化するために、以下のような機能を提供しています。
1. 型チェックの強化：型の不整合を検出し、適切な型を指定するよう推奨します。
2. 未定義変数の検出：定義されていない変数や関数の使用を警告します。
3. コードの最適化提案：不要なコードや冗長な処理を指摘します。
4. プラグインによる拡張：カスタムルールを追加し、特定のコーディング規約に準拠させることが可能です。
5. CI/CDとの統合：GitHub ActionsやGitLab CIなどと連携し、自動でコードチェックを実行できます。

PHPコードの品質向上におけるPsalmの重要性

Psalmは、単なるエラー検出ツールではなく、コードの品質向上にも貢献します。
コードの一貫性を保ち、バグの混入を防ぐことで、開発者が安心してリファクタリングできる環境を提供します。
また、Psalmを導入することで、チーム開発においても統一されたコーディングスタイルを維持しやすくなります。
特に、長期間運用するプロジェクトでは、コードの可読性を向上させることで、将来的なメンテナンスコストを削減できます。

他の静的解析ツールとの違いとPsalmの強み

PHPStanなどの他の静的解析ツールと比較すると、Psalmは型の厳密なチェック機能が強みです。
たとえば、PHPStanが検出できない型の不整合や、詳細なDocBlockアノテーションの解析が可能です。
また、Psalmは、開発者向けに拡張性の高い設計がされており、独自のプラグインを追加することで、解析のルールをカスタマイズできます。
これにより、企業やプロジェクトごとに最適化されたコードチェックが実現できます。
次に、Psalmのインストール方法について解説します。

Psalmのインストール方法とセットアップ手順を解説

Psalmの導入は非常に簡単で、Composerを利用することで素早くインストールできます。
PHPのプロジェクトにPsalmを追加することで、静的解析を導入し、コード品質の向上を図ることができます。
本セクションでは、Psalmのインストール手順や基本的なセットアップ方法を詳しく解説します。

Psalmのインストール方法（Composerを使用）

PsalmはComposerを使用してインストールするのが一般的です。
以下のコマンドを実行することで、プロジェクトにPsalmを導入できます。

composer require --dev vimeo/psalm

このコマンドにより、`vendor/bin/psalm` にPsalmがインストールされ、プロジェクト内で使用できるようになります。
`–dev` オプションを指定することで、開発環境のみで利用可能なパッケージとしてインストールされます。

Psalmの初期設定とプロジェクトへの適用方法

Psalmを初めて実行する際には、以下のコマンドを使用して初期設定を行います。

vendor/bin/psalm --init

このコマンドを実行すると、`psalm.xml` という設定ファイルが自動生成されます。
設定ファイルには、解析対象のディレクトリや、解析レベルの設定が含まれています。
この設定を適切に調整することで、プロジェクトに最適な解析環境を構築できます。

Psalmのバージョン管理とアップデート手順

Psalmは頻繁にアップデートされるため、定期的に最新バージョンを適用することが推奨されます。
バージョンを更新するには、以下のコマンドを使用します。

composer update vimeo/psalm

特定のバージョンを指定してアップデートする場合は、`composer.json` の `require-dev` セクションでバージョンを指定し、再度 `composer update` を実行してください。

Psalmの依存関係と推奨される環境設定

Psalmを使用するには、PHP 7.1以上のバージョンが必要です。
また、プロジェクトのコードスタイルに応じた設定を適用することで、より適切な静的解析が可能になります。
たとえば、LaravelやSymfonyなどのフレームワークと併用する場合は、追加のプラグインを導入すると効果的です。

トラブルシューティング：インストール時のエラー対応

Psalmのインストール時にエラーが発生することがあります。
よくある問題として、PHPのバージョンが古い、Composerのキャッシュが破損しているなどが挙げられます。
以下のコマンドでキャッシュをクリアし、再インストールを試みてください。

composer clear-cache
composer install

Psalmの基本的な使い方とコード解析の流れを理解する

Psalmは、PHPコードの静的解析を行うツールとして、開発者にとって非常に強力なサポートを提供します。
Psalmを導入することで、コードの品質を向上させ、バグの混入を防ぐことが可能になります。
本セクションでは、Psalmの基本的なコマンドや解析の流れについて詳しく解説します。
Psalmの基本的な使い方として、まずはコマンドラインでPsalmを実行し、コードを解析する方法を学びます。
次に、解析結果の読み方やエラーの種類、修正方法について説明します。
また、カスタムルールの設定や、継続的なコード品質管理のための活用方法についても紹介します。
Psalmを効果的に活用することで、開発の効率化とバグの削減を実現できるでしょう。

Psalmの基本的なコマンドとその実行方法

Psalmを実行するには、コマンドラインから以下のコマンドを使用します。

vendor/bin/psalm

このコマンドを実行すると、プロジェクト内のすべてのPHPファイルに対して解析が行われ、問題点が出力されます。
出力結果には、エラーの内容や警告が含まれ、どのコードに問題があるのかが明示されます。
特定のファイルやディレクトリのみを解析したい場合は、以下のようにファイルパスを指定することも可能です。

vendor/bin/psalm src/
vendor/bin/psalm src/MyClass.php

解析の速度を向上させるために、`–diff` オプションを使用して変更のあったファイルのみ解析することもできます。

vendor/bin/psalm --diff

解析結果の読み方とエラーの種類

Psalmの解析結果は、主に「エラー」「警告」「情報」の3種類に分類されます。
– エラー（Error）: 重大な問題であり、コードの実行時にエラーが発生する可能性がある。
– 警告（Warning）: 潜在的なバグや非推奨の書き方に関する警告。
– 情報（Info）: 推奨される改善点やコードの最適化に関する情報。
例えば、以下のようなエラーが出力されることがあります。

ERROR: UndefinedVariable - src/MyClass.php:10:5 - Variable $foo is not defined

このメッセージは、「`src/MyClass.php` の10行目で `$foo` という変数が定義されていない」というエラーを示しています。
解析結果を正しく理解することで、コードの修正が容易になります。

エラーや警告の修正方法とベストプラクティス

Psalmが検出したエラーや警告を修正する際には、次のような手順を踏むと効果的です。
1. エラーメッセージを確認する: 出力されたメッセージを読み、問題の発生箇所を特定する。
2. 公式ドキュメントを参照する: Psalmの公式サイトやGitHubのドキュメントには、エラーの詳細な説明が記載されている。
3. コードを修正する: 型を明示的に指定する、未定義の変数を適切に初期化するなどの対応を行う。
4. 再度Psalmを実行する: 修正後にPsalmを再実行し、エラーが解消されたかを確認する。
例えば、未定義変数のエラーが発生した場合、以下のように修正することで解決できます。
修正前（エラーが発生するコード）

function example() {
    echo $foo; // Undefined variable error
}

修正後

function example() {
    $foo = "Hello, world!";
    echo $foo;
}

このように、Psalmの解析結果を活用することで、より安全なコードを書くことができます。

カスタムルールの設定方法と応用例

Psalmは、`psalm.xml` 設定ファイルを編集することでカスタムルールを適用できます。
たとえば、特定の型チェックを強化する場合、以下のように設定ファイルを変更できます。

<psalm>
    <projectFiles>
        <directory name="src" />
    </projectFiles>
    <issueHandlers>
        <UndefinedVariable errorLevel="error" />
    </issueHandlers>
</psalm>

この設定により、未定義変数の使用が検出された場合にエラーとして扱われるようになります。
また、特定のディレクトリを解析対象から除外したい場合は、以下のように設定できます。

<projectFiles>
    <directory name="src" />
    <ignoreFiles>
        <file name="tests/" />
    </ignoreFiles>
</projectFiles>

このように、Psalmの設定をカスタマイズすることで、プロジェクトの特性に合わせた解析ルールを適用できます。

Psalmを用いた継続的なコード品質管理

Psalmは、一度だけ実行するのではなく、開発フローの一部として継続的に使用することで、最大限の効果を発揮します。
特に、CI/CD環境に組み込むことで、自動的にコードの品質をチェックできるため、開発の効率化につながります。
例えば、GitHub Actionsを使用してPsalmを実行する場合、以下のようなワークフローを設定できます。

name: Psalm Static Analysis
on: [push, pull_request]
jobs:
  psalm:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.0'
      - name: Install dependencies
        run: composer install --prefer-dist --no-progress
      - name: Run Psalm
        run: vendor/bin/psalm

この設定により、新しいコードがプッシュされるたびにPsalmが自動で実行され、エラーの有無が確認されます。
エラーが発生した場合は、開発者に通知が送られ、修正が求められます。

Psalmの設定ファイル（psalm.xml）の作成と設定の詳細

Psalmの利用を最適化するためには、設定ファイル（`psalm.xml`）の作成と適切な設定が不可欠です。
この設定ファイルを利用することで、解析対象の指定、エラーレベルの調整、カスタムルールの追加などを行うことができます。
特に大規模なプロジェクトでは、プロジェクトごとに最適な設定を適用することが求められます。
本セクションでは、`psalm.xml` の基本的な構造やカスタマイズ方法、プロジェクトごとの最適な設定について詳しく解説します。
これにより、Psalmの機能を最大限に活用し、より安全なPHPコードを記述できるようになります。

psalm.xmlとは？設定ファイルの役割と構造

`psalm.xml` は、Psalmの動作を制御するためのXML形式の設定ファイルです。
このファイルでは、解析対象のディレクトリや除外するファイル、エラーレベルのカスタマイズ、特定のルールの有効化などを設定できます。
基本的な`psalm.xml` の構造は以下のようになります。

<?xml version="1.0"?>
<psalm>
    <projectFiles>
        <directory name="src"/>
        <ignoreFiles>
            <file name="tests/"/>
        </ignoreFiles>
    </projectFiles>
    <issueHandlers>
        <UndefinedVariable errorLevel="error"/>
        <PossiblyUndefinedVariable errorLevel="warning"/>
    </issueHandlers>
</psalm>

この設定では、`src/` ディレクトリ内のファイルのみを解析対象とし、`tests/` ディレクトリを除外しています。
また、未定義変数をエラーとして扱い、可能性のある未定義変数は警告として扱うように設定しています。

プロジェクトごとのカスタマイズ設定の方法

プロジェクトによっては、デフォルトの設定では不十分な場合があります。
そのため、`psalm.xml` を適切にカスタマイズすることで、プロジェクトに最適な解析環境を構築できます。
例えば、以下のような設定を追加することで、特定のPHPバージョンに合わせた解析を行うことができます。

<psalm>
    <phpVersion>8.0</phpVersion>
</psalm>

また、解析レベルを変更することで、チェックの厳密さを調整できます。

<psalm>
    <level>3</level>
</psalm>

レベルの値は `1`（最も厳密）から `8`（最も緩やか）までの範囲で指定できます。
開発初期段階では緩やかな設定を適用し、コード品質を向上させるにつれて厳密なレベルに変更するのが推奨されます。

解析対象ファイルと除外ファイルの指定方法

Psalmの解析対象を明示的に指定することで、不要な解析を防ぎ、パフォーマンスを向上させることができます。
`` セクションで解析対象のディレクトリを指定できます。

<projectFiles>
    <directory name="app"/>
    <directory name="src"/>
</projectFiles>

また、特定のファイルやディレクトリを解析対象から除外するには、`` セクションを使用します。

<ignoreFiles>
    <file name="vendor/"/>
    <file name="storage/"/>
</ignoreFiles>

特に、`vendor/` ディレクトリを除外することで、外部ライブラリの解析をスキップし、解析速度を向上させることができます。

エラーや警告レベルのカスタマイズ設定

Psalmでは、特定のエラーの扱いを変更することができます。
例えば、未使用の変数を警告として扱いたい場合は、以下のように設定します。

<issueHandlers>
    <UnusedVariable errorLevel="warning"/>
</issueHandlers>

また、特定の警告を完全に無視する場合は、`suppress` を使用します。

<issueHandlers>
    <PossiblyUnusedVariable errorLevel="suppress"/>
</issueHandlers>

このように、エラーレベルをカスタマイズすることで、プロジェクトに適した解析ルールを適用できます。

設定ファイルの管理とバージョン管理のポイント

`psalm.xml` はプロジェクトの一部としてバージョン管理することが重要です。
特に、チーム開発では設定ファイルを適切に管理することで、全員が統一されたルールのもとで開発を進めることができます。
Gitで設定ファイルを管理する場合、`psalm.xml` をリポジトリに含め、定期的にレビューを行うことが推奨されます。

git add psalm.xml
git commit -m "Add Psalm configuration file"

また、プロジェクトの要件に応じて設定を変更する際には、変更履歴をしっかりと記録し、影響範囲を確認することが重要です。

Psalmの実行方法とオプション設定の解説

Psalmを効果的に利用するためには、基本的な実行方法とオプション設定を理解することが重要です。
Psalmはシンプルなコマンドで静的解析を実行できますが、プロジェクトごとの要件に応じてオプションを適用することで、より柔軟な解析が可能になります。
本セクションでは、Psalmの基本的な実行コマンドや、解析結果を出力する方法、特定のファイルやディレクトリのみを対象とした解析方法、コード修正を自動化するフィックスモードについて詳しく解説します。
さらに、CI/CD環境でPsalmを運用する際の実行設定についても紹介します。

基本的なPsalmの実行方法と使用コマンド

Psalmの基本的な実行は、以下のコマンドで行います。

vendor/bin/psalm

このコマンドを実行すると、プロジェクト内の全ファイルを解析し、検出された問題点をレポートとして表示します。
特定のファイルのみ解析したい場合は、以下のようにファイル名を指定できます。

vendor/bin/psalm src/MyClass.php

また、特定のディレクトリを対象に解析することも可能です。

vendor/bin/psalm src/

これにより、大規模なプロジェクトでも必要な部分だけを解析し、実行時間を短縮できます。

実行時のオプションと解析結果の出力形式

Psalmはさまざまなオプションをサポートしており、解析結果の出力形式をカスタマイズできます。
例えば、エラーレポートをJSON形式で出力する場合、以下のようにオプションを指定します。

vendor/bin/psalm --output-format=json

他にも、以下のような出力形式が利用可能です。
– console（デフォルト）: 標準出力に解析結果を表示
– json: JSON形式で出力
– xml: XML形式で出力
– github: GitHub Actions向けの出力形式
CI/CD環境でPsalmを利用する場合は、`json` や `xml` を利用すると、自動解析結果をログに記録しやすくなります。

特定のディレクトリやファイルの解析指定

大規模プロジェクトでは、変更のあったファイルのみ解析することで、解析の時間を短縮できます。
`–diff` オプションを利用すると、Gitの変更履歴を基に、差分のみを解析できます。

vendor/bin/psalm --diff

また、特定のディレクトリやファイルを除外するには、`–ignore-baseline` オプションを使用します。

vendor/bin/psalm --ignore-baseline

このオプションを使用すると、過去に無視したエラーも再度チェックされるため、コードのリファクタリング時に役立ちます。

コード修正の自動化：Psalmのフィックスモード

Psalmには、静的解析で発見された問題を自動で修正する「フィックスモード」が搭載されています。
フィックスモードを実行するには、以下のコマンドを使用します。

vendor/bin/psalm --alter

このコマンドを実行すると、Psalmがコードを修正し、適切な型アノテーションを追加します。
例えば、関数の戻り値の型を推測し、自動的にPHPDocに追加することができます。
修正前

function getUser($id) {
    return ['id' => $id, 'name' => 'John Doe'];
}

修正後（Psalmによる自動修正）

/
 * @return array{id: int, name: string}
 */
function getUser($id) {
    return ['id' => $id, 'name' => 'John Doe'];
}

この機能を活用することで、型アノテーションの記述ミスを防ぎ、コードの可読性を向上させることができます。

CI/CD環境でPsalmを利用する際の実行設定

PsalmをCI/CDパイプラインに統合することで、コードの品質管理を自動化できます。
例えば、GitHub Actionsを利用して、リポジトリにプッシュされたコードを自動的にチェックする設定を行うことができます。
以下は、GitHub ActionsでPsalmを実行するワークフローの例です。

name: Run Psalm Static Analysis
on: [push, pull_request]
jobs:
  psalm:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.0'
      - name: Install dependencies
        run: composer install --prefer-dist --no-progress
      - name: Run Psalm
        run: vendor/bin/psalm

この設定により、新しいコードがプッシュされた際にPsalmが自動実行され、問題があれば開発者に通知されます。

Psalmで検出できる問題点とその具体的な例

PsalmはPHPコードの静的解析を行うことで、さまざまな問題点を検出できます。
コードを実行する前に潜在的なエラーを発見できるため、バグの修正にかかる工数を削減し、より安全で保守しやすいコードを書くことが可能になります。
本セクションでは、Psalmが検出できる主な問題点について詳しく解説します。
具体的には、型の不整合、未使用変数や未定義関数、Null安全性チェック、コード品質向上に役立つアナライザー機能、そして実際のエラーメッセージとその解決策について紹介します。

型の不整合に関する警告と修正方法

Psalmの主な機能のひとつに、型の不整合を検出する機能があります。
PHPは動的型付け言語のため、異なる型のデータを扱うことが可能ですが、これがバグの原因になることがあります。
Psalmを利用することで、型のミスを未然に防ぐことができます。
例えば、以下のコードでは整数型の引数を受け取るべき関数に文字列を渡してしまっています。

function add(int $a, int $b): int {
    return $a + $b;
}
echo add("10", 5); // Psalmがエラーを検出

Psalmはこのコードを解析し、「`string` 型の値を `int` 型のパラメータに渡している」というエラーを出力します。
この問題を修正するには、型のキャストを行うか、適切な入力を渡す必要があります。

未使用変数や未定義関数の検出と対応

Psalmは、定義されたが使用されていない変数や、定義されていない関数の呼び出しを検出することもできます。
これにより、無駄なコードを排除し、コードの可読性を向上させることができます。
例えば、未使用変数の例を見てみましょう。

function example() {
    $unusedVar = "Hello, world!"; // この変数はどこでも使われていない
    echo "Example function";
}

このコードをPsalmで解析すると、「未使用の変数 `$unusedVar` が存在する」という警告が表示されます。
不要な変数を削除することで、コードのクリーンアップが可能になります。

Null安全性チェックとその重要性

PHPでは `null` の取り扱いが重要ですが、誤って `null` を処理しようとすると、エラーが発生することがあります。
Psalmは `null` を安全に扱うためのチェック機能を提供し、適切なコードを書く手助けをしてくれます。
以下のコードは、未定義の値が `null` である可能性を無視しているため、エラーを引き起こす可能性があります。

function getUser(): ?string {
    return null;
}
echo strtoupper(getUser()); // null値に対してstrtoupperを実行しようとする

Psalmは「`null` の可能性がある値に対して `strtoupper` を実行している」と警告を出します。
これを修正するには、`null` チェックを追加する必要があります。

$user = getUser();
if ($user !== null) {
    echo strtoupper($user);
} else {
    echo "No user found.";
}

このように、Psalmを活用することで、`null` に起因するエラーを未然に防ぐことができます。

コード品質向上に役立つアナライザー機能

Psalmは、単なるエラーチェックだけでなく、コード品質を向上させるためのアナライザー機能も備えています。
例えば、冗長なコードや非推奨の関数の使用を検出し、最適な書き方を提案します。
例えば、以下のようなコードは改善の余地があります。

function isAdult($age) {
    if ($age >= 18) {
        return true;
    } else {
        return false;
    }
}

Psalmはこのコードに対して、「冗長な条件分岐を最適化できる」と提案します。
以下のように修正することで、コードを簡潔にできます。

function isAdult($age) {
    return $age >= 18;
}

このような改善提案を活用することで、より洗練されたコードを書くことが可能になります。

実際のエラーメッセージとその解決策

Psalmが出力するエラーメッセージを正しく理解し、適切に対処することが重要です。
以下に、Psalmが出力する典型的なエラーメッセージとその解決策を紹介します。
例1: 未定義の変数

ERROR: UndefinedVariable - src/MyClass.php:10:5 - Variable $foo is not defined

解決策: `$foo` を事前に定義する。

$foo = "Hello";
echo $foo;

例2: 型の不一致

ERROR: InvalidArgument - src/User.php:5:10 - Argument 1 expects int, string provided

解決策: 関数の引数を適切な型に修正するか、型キャストを行う。

function add(int $a, int $b): int {
    return $a + $b;
}
echo add((int)"10", 5);

このように、Psalmが出力するエラーメッセージを適切に解析し、修正を行うことで、より安全なPHPコードを書くことができます。

Psalmの解析レベルと厳密さの調整方法を徹底解説

Psalmの解析レベルは、コードの厳密なチェックを調整するための重要な設定です。
解析レベルを変更することで、より多くのバグを検出できるようになりますが、その分、エラーの数が増え、修正が必要になる場合もあります。
適切な解析レベルを選ぶことで、プロジェクトの開発段階や品質基準に合わせた柔軟な静的解析が可能になります。
本セクションでは、Psalmの解析レベルの概要、各レベルの違い、適切なレベルの選び方、プロジェクトに応じた設定方法、解析レベル変更時の影響と注意点について詳しく解説します。

解析レベルとは？Psalmの厳密度を理解する

Psalmの解析レベルは、`1` から `8` までの8段階に設定できます。
`1` が最も厳格であり、より多くの警告やエラーが検出されます。
一方、`8` は最も緩やかで、致命的なエラーのみを検出します。
解析レベルを確認・変更するには、以下のように `psalm.xml` の `` タグを変更します。

<psalm>
    <level>3</level>
</psalm>

また、コマンドラインから一時的に解析レベルを変更することも可能です。

vendor/bin/psalm --set-baseline=psalm-baseline.xml --level=2

この設定により、プロジェクトの成長に応じて解析レベルを段階的に引き上げることができます。

各解析レベルの違いと適切な選び方

Psalmの各解析レベルの違いを理解することで、プロジェクトに適したレベルを選択できます。
以下に、代表的な解析レベルの特徴を示します。

解析レベル 特徴
1 最も厳格なレベル。型の厳密なチェックが必要で、新規プロジェクト向け。
2-3 一般的な開発環境で推奨されるレベル。エラーと潜在的なバグを適度に検出。
4-5 実用的なレベル。チーム開発に適しており、エラーの数も適度。
6-7 許容範囲の広いレベル。古いコードベースのリファクタリング時に適用可能。
8 最も緩やかなレベル。致命的なエラーのみを検出。

例えば、新規プロジェクトで厳密な型チェックを行いたい場合はレベル`1`を設定し、既存の大規模プロジェクトで段階的に導入したい場合はレベル`5`や`6`を選択すると良いでしょう。

特定の解析レベルで検出されるエラーの種類

解析レベルを高くすると、Psalmがより多くのエラーを検出するようになります。
代表的なエラーの種類を以下に示します。
1. 型の不整合 (`InvalidArgument`)

   function add(int $a, int $b): int {
       return $a + $b;
   }
   echo add("10", 5); // string型が渡されるためエラー

2. 未定義変数 (`UndefinedVariable`)

   function example() {
       echo $foo; // $foo が未定義のためエラー
   }

3. Null値の可能性 (`PossiblyNullReference`)

   function getUser(): ?string {
       return null;
   }
   echo strtoupper(getUser()); // Null値に対する操作でエラー

4. 未使用の変数 (`UnusedVariable`)

   function test() {
       $unused = "Hello"; // どこでも使われていないため警告
   }

5. 未使用のメソッド (`PossiblyUnusedMethod`)

   class User {
       private function secretMethod() {} // どこからも呼ばれていない
   }

これらのエラーをチェックし、適切に修正することで、より堅牢なコードを実装できます。

プロジェクトに応じた適切な解析レベルの設定

プロジェクトの状況に応じて、適切な解析レベルを設定することが重要です。
例えば、以下のようなケースでは、異なる解析レベルを採用すると良いでしょう。
1. 新規プロジェクトの場合
– `level=”1″` に設定し、厳格な型チェックを適用する。
– 型の安全性を保ち、将来的なメンテナンスを容易にする。
2. 既存のプロジェクトに導入する場合
– `level=”5″` など緩やかな設定から始め、徐々に厳しくする。
– 大量のエラーを一度に修正するのは負担が大きいため、段階的な適用が推奨される。
3. レガシーコードを改善する場合
– `level=”7″` 以上の緩やかな設定で導入し、少しずつ厳しくする。
– まずは致命的なバグの修正を優先し、後から細かいルールを適用。
このように、プロジェクトのフェーズに応じた解析レベルの設定を行うことで、効果的にPsalmを活用できます。

解析レベルを変更した際の影響と注意点

解析レベルを変更すると、検出されるエラーや警告の数が大きく変わります。
特に、厳格なレベルに変更すると、一度に大量のエラーが検出されることがあるため、適切な対応が求められます。
解析レベルを変更する際の注意点は以下の通りです。
1. 段階的に変更する
– いきなりレベル`1`にすると、エラーの量が多すぎて対応しきれない可能性がある。
– まずは `level=”5″` から始め、徐々に `4` → `3` と厳しくしていく。
2. エラーの対応方針を決める
– すべてのエラーを修正するのか、一部を無視するのか、事前に方針を決めておく。
– `suppress` や `ignore-baseline` のオプションを活用して、一時的に特定のエラーを無視することも可能。
3. CI/CD環境での適用
– CI/CD環境にPsalmを統合している場合、解析レベルを上げるとビルドが失敗する可能性がある。
– 事前にローカル環境で解析を行い、問題がないことを確認してから適用する。

PsalmとPHPStanの比較：機能や使用感の違いを検証

PHPの静的解析ツールとして、PsalmとPHPStanは広く利用されています。
どちらもコードの品質向上やバグの早期発見に役立ちますが、それぞれに特徴や強みがあり、用途によって使い分ける必要があります。
本セクションでは、PsalmとPHPStanの違いを比較し、機能や使用感、設定ファイルの違い、プロジェクトごとの適切な選択方法、両者の併用の可否について詳しく解説します。
PsalmとPHPStanのどちらを選ぶべきか悩んでいる開発者や、すでにPHPStanを導入していてPsalmへの移行を検討している方にとって、有益な情報を提供します。

PsalmとPHPStanの基本的な違いとは？

PsalmとPHPStanはどちらもPHPの静的解析ツールですが、それぞれ異なるアプローチでコードをチェックします。
以下に、両者の主な違いを比較した表を示します。

特徴 Psalm PHPStan
開発元 Facebook (Meta) 独立系開発者
型チェック 非常に厳格 比較的柔軟
拡張性 プラグインによる拡張が可能 ルールセットで拡張が可能
設定の柔軟性 XMLベースで詳細設定が可能 NEONファイルを使用した簡潔な設定
実行速度 一般的に高速だが設定に依存 解析内容によってはPsalmより速い
対応PHPバージョン PHP 7.1以上対応 PHP 7.1以上対応

PsalmはFacebookが開発したツールで、特に型チェックの厳密さに優れています。
一方、PHPStanは比較的柔軟なチェックができ、設定が簡単な点が魅力です。

PsalmとPHPStanの解析精度とパフォーマンス比較

Psalmは型の厳密な解析に重点を置いており、PHPDocの型アノテーションを最大限に活用します。
一方、PHPStanはデフォルトで型を推測するため、ある程度の柔軟性があります。
以下のコードを例に、PsalmとPHPStanの解析結果の違いを見てみましょう。

function add($a, $b) {
    return $a + $b;
}

Psalmを実行すると、`$a` と `$b` の型が不明であるためエラーが発生します。

ERROR: MixedArgument - Argument 1 and 2 have mixed types, consider adding type hints.

一方、PHPStanはデフォルトでは警告を出しませんが、`strict-rules` を有効にすると、同様の警告を出すようになります。
このように、Psalmはデフォルトで型チェックが厳しいため、大規模なプロジェクトでの型安全性の向上に適しています。
一方、PHPStanは設定次第で柔軟な解析が可能であり、既存のコードに導入しやすいメリットがあります。

PsalmとPHPStanの設定ファイルの違いとカスタマイズ

Psalmは `psalm.xml` というXML形式の設定ファイルを使用し、PHPStanは `phpstan.neon` というNEON形式の設定ファイルを使用します。
それぞれの設定例を見てみましょう。
Psalmの設定ファイル（psalm.xml）

<psalm>
    <projectFiles>
        <directory name="src"/>
    </projectFiles>
    <level>3</level>
</psalm>

PHPStanの設定ファイル（phpstan.neon）

parameters:
    level: 3
    paths:
        - src

Psalmの設定はXMLで詳細なカスタマイズが可能なのに対し、PHPStanの設定はYAMLベースでシンプルに記述できるため、設定ファイルの可読性ではPHPStanが有利です。

どちらを選ぶべき？プロジェクトごとの最適な選択

PsalmとPHPStanのどちらを選ぶべきかは、プロジェクトの性質やチームの開発方針によって異なります。
以下の基準を参考にすると良いでしょう。
1. 新規プロジェクトで厳格な型チェックを求める場合
→ Psalmが適している。

型安全性を最大限に活かし、将来的なメンテナンスコストを削減できる。
2. 既存プロジェクトに静的解析を導入する場合
→ PHPStanが適している。

設定が簡単で、エラーの出力が比較的緩やかなため、段階的な導入が可能。
3. CI/CDに統合して継続的にコード品質を向上させたい場合
→ どちらも適している。

ただし、Psalmはデフォルトでエラーが厳しく出るため、PHPStanのほうが導入しやすい場合もある。

PsalmとPHPStanの併用は可能？メリットとデメリット

PsalmとPHPStanは、ある程度の機能が重複しているため、通常はどちらか一方を選択するのが一般的です。
しかし、両方を併用することも技術的には可能です。
併用のメリット
– Psalmの厳密な型チェックと、PHPStanの柔軟なルール設定を組み合わせることで、より強力な解析が可能。
– 各ツールが提供するプラグインや拡張機能を相互に活用できる。
併用のデメリット
– 設定が複雑になり、メンテナンスが難しくなる。
– 両方の解析結果を管理する必要があり、開発コストが増加する。
例えば、Psalmをメインの型チェックツールとして使用し、PHPStanを補助的に活用するというアプローチも考えられます。

vendor/bin/psalm && vendor/bin/phpstan analyse

ただし、併用することで開発の手間が増えるため、プロジェクトの規模や要件に応じて慎重に検討する必要があります。

Psalmのプラグイン機能を活用して解析能力を拡張する

Psalmはデフォルトでも強力な静的解析機能を備えていますが、プラグイン機能を活用することで、さらなる解析能力の拡張が可能です。
プラグインを導入することで、プロジェクトに特化したカスタムルールを追加したり、特定のフレームワークやライブラリに最適化した解析を行ったりできます。
本セクションでは、Psalmのプラグイン機能の概要、公式プラグインとカスタムプラグインの違い、プラグインのインストール方法、カスタムプラグインの作成手順、そしてプロジェクトに適したプラグインの選び方について詳しく解説します。

Psalmのプラグイン機能とは？導入のメリット

Psalmのプラグイン機能を利用すると、標準機能ではカバーできない独自の解析ルールを追加できます。
例えば、以下のような用途で活用できます。
– LaravelやSymfonyなどのフレームワーク固有のルールを適用
– カスタムアノテーションを利用した独自の型チェック
– 特定のコーディング規約に従うコードスタイル解析
– 静的解析の範囲を拡張し、さらに詳細なチェックを実施
プラグインを利用することで、プロジェクトの特性に合わせた解析が可能となり、より厳密なコード品質管理が実現できます。

公式プラグインとカスタムプラグインの違い

Psalmには、公式で提供されているプラグインと、独自に開発できるカスタムプラグインの2種類があります。
1. 公式プラグイン
– Psalmの開発チームやコミュニティが提供するプラグイン
– `composer` で簡単にインストール可能
– 代表的なものに、Laravel向けプラグインやPHPUnit向けプラグインがある
2. カスタムプラグイン
– 自分で作成し、独自の解析ルールを定義できる
– プロジェクトの要件に特化したルールの追加が可能
– JSON、XML、PHPコードを用いて定義する
公式プラグインは即座に導入できる点がメリットで、カスタムプラグインはプロジェクト固有のニーズに対応できる点が強みです。

プラグインのインストール方法と管理

Psalmの公式プラグインは、`composer` を使用してインストールできます。
例えば、Laravelのプラグインを導入する場合は、以下のコマンドを実行します。

composer require --dev vimeo/psalm-plugin-laravel

インストール後、Psalmにプラグインを登録する必要があります。
以下のコマンドで有効化できます。

vendor/bin/psalm --init
vendor/bin/psalm-plugin enable vimeo/psalm-plugin-laravel

また、登録済みのプラグインを一覧表示するには、次のコマンドを実行します。

vendor/bin/psalm-plugin list

プラグインの設定は `psalm.xml` に記述することもできます。

<psalm>
    <plugins>
        <pluginClass class="Psalm\LaravelPlugin"/>
    </plugins>
</psalm>

このように、必要なプラグインを設定ファイルに記述しておくことで、プロジェクト内で一貫した設定を維持できます。

カスタムプラグインの作成方法と活用例

Psalmのカスタムプラグインを作成することで、特定のルールをチェックする機能を追加できます。
例えば、「すべてのクラス名は `CamelCase` でなければならない」というルールを定義するプラグインを作成する場合、以下のように実装します。
1. カスタムプラグインのPHPクラスを作成

namespace CustomPsalmPlugin;
use Psalm\Plugin\PluginEntryPointInterface;
use Psalm\Plugin\PluginInterface;
use SimpleXMLElement;
class CustomPlugin implements PluginEntryPointInterface
{
    public function __invoke(): void
    {
        echo "Custom Plugin Initialized";
    }
}

2. `psalm.xml` にプラグインを登録

<psalm>
    <plugins>
        <pluginClass class="CustomPsalmPlugin\CustomPlugin"/>
    </plugins>
</psalm>

3. Psalmを実行してプラグインを適用

vendor/bin/psalm

このように、カスタムプラグインを作成することで、プロジェクト特有のルールをチェックできるようになります。

プロジェクトに適したプラグインの選び方

Psalmのプラグインを選ぶ際には、以下のポイントを考慮すると良いでしょう。
1. 使用しているフレームワークに適したものを選ぶ
– Laravel, Symfony, WordPress などのプロジェクトなら、それぞれに対応したプラグインを活用
2. 解析対象の範囲を明確にする
– 型チェックを強化したいなら `psalm-strict-rules`
– テストコードの品質を向上させたいなら `psalm-plugin-phpunit`
3. チーム開発に適したルールを追加
– コーディング規約の統一を目的とする場合は、カスタムプラグインの作成を検討
4. パフォーマンスを考慮
– 解析速度を重視する場合、不要なプラグインを無効化して最適化する
適切なプラグインを選定し、プロジェクトのニーズに応じた設定を行うことで、Psalmを最大限に活用できます。

CIツールとPsalmの連携方法：自動コードチェックの実践

Psalmは静的解析ツールとして、コードの品質向上に大きく貢献しますが、開発ワークフローに統合することで、その効果をさらに高めることができます。
特に、CI（継続的インテグレーション）ツールと連携することで、コードがプッシュされるたびに自動で解析が行われ、品質の低下を防ぐことが可能になります。
本セクションでは、CIツールとPsalmを連携するメリット、GitHub ActionsやGitLab CI/CDを利用した自動解析の設定方法、CircleCIやTravis CIでのPsalmの実行方法、そしてCIツール上でのエラー管理と通知設定について詳しく解説します。

CIツールとPsalmを連携するメリットとは？

CIツールとPsalmを連携することで、以下のようなメリットがあります。
1. コード品質の維持
– Pull RequestごとにPsalmを実行し、品質基準を満たしていないコードのマージを防ぐ。
2. 開発効率の向上
– エラーが自動検出されるため、手動でのチェックが不要になり、開発者の負担を軽減。
3. バグの早期発見
– 変更が加えられた際に即座に問題点を特定できるため、本番環境でのバグ発生を抑制。
4. 統一されたコーディング基準の適用
– チーム全体で同じルールを適用し、一貫したコード品質を維持できる。
5. 開発フローの自動化
– CI/CDパイプラインの一部としてPsalmを導入することで、静的解析を自動化し、コードレビューの精度を向上させる。

GitHub Actionsを用いたPsalmの自動実行

GitHub Actionsを利用すると、リポジトリにコードがプッシュされた際に自動でPsalmを実行し、エラーを検出できます。
以下は、GitHub Actionsの設定例です。
1. `.github/workflows/psalm.yml` を作成

name: Run Psalm Static Analysis
on: [push, pull_request]
jobs:
  psalm:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2
      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.1'
          tools: composer
      - name: Install dependencies
        run: composer install --prefer-dist --no-progress
      - name: Run Psalm
        run: vendor/bin/psalm

設定のポイント:
– `on: [push, pull_request]` により、プッシュやプルリクエスト時にPsalmを実行。
– `shivammathur/setup-php@v2` を使用してPHP環境をセットアップ。
– `composer install` で依存関係をインストール後、`vendor/bin/psalm` を実行。
このワークフローを設定することで、新しいコードが追加された際にPsalmが自動実行され、エラーがある場合は開発者に通知が送られます。

GitLab CI/CDとPsalmの統合手順

GitLab CI/CDを利用してPsalmを実行する場合、`.gitlab-ci.yml` に以下の設定を追加します。

stages:
  - static_analysis
psalm:
  stage: static_analysis
  image: php:8.1
  before_script:
    - apt-get update && apt-get install -y unzip
    - curl -sS https://getcomposer.org/installer | php
    - php composer.phar install --no-interaction --prefer-dist
  script:
    - vendor/bin/psalm
  only:
    - merge_requests
    - main

設定のポイント:
– `psalm` ジョブを `static_analysis` ステージで実行。
– `image: php:8.1` により、PHP 8.1の環境を使用。
– `only: – merge_requests – main` により、マージリクエストと `main` ブランチでのみ実行。
この設定を適用することで、GitLab CI/CDでPsalmを自動実行し、問題のあるコードをマージ前にブロックできます。

CircleCIやTravis CIでPsalmを設定する方法

CircleCI
CircleCIを利用してPsalmを実行する場合、`.circleci/config.yml` に以下のような設定を追加します。

version: 2.1
jobs:
  psalm:
    docker:
      - image: circleci/php:8.1
    steps:
      - checkout
      - run: composer install --no-interaction --prefer-dist
      - run: vendor/bin/psalm
workflows:
  version: 2
  static_analysis:
    jobs:
      - psalm

Travis CI
Travis CIを利用する場合、`.travis.yml` に以下の設定を追加します。

language: php
php:
  - 8.1
install:
  - composer install --no-interaction --prefer-dist
script:
  - vendor/bin/psalm

どちらの設定も、`composer install` で依存関係をインストールし、その後Psalmを実行するシンプルな流れになっています。

CIツール上でのPsalmのエラー管理と通知設定

CI環境でPsalmを実行した際にエラーが発生した場合、開発者へ通知を送ることで、迅速な対応が可能になります。
1. GitHub Actionsでの通知設定
GitHub Actionsでは、エラーが発生した際にSlackやメールで通知を送ることが可能です。

      - name: Notify on Failure
        if: failure()
        run: |
          curl -X POST -H 'Content-type: application/json' --data '{"text":"Psalm analysis failed!"}' $SLACK_WEBHOOK_URL

2. GitLab CI/CDでのエラー通知
GitLabでは、エラーが発生した際に通知を送る設定を `.gitlab-ci.yml` に追加できます。

after_script:
  - if [ "$CI_JOB_STATUS" != "success" ]; then curl -X POST --data "Psalm analysis failed" $SLACK_WEBHOOK_URL; fi

3. CIツールのステータスバッジ
CIの実行ステータスをREADMEに表示することで、開発者がプロジェクトの品質を把握しやすくなります。

![Psalm Static Analysis](https://github.com/your-repo/badge.svg)

このように、CI/CD環境にPsalmを組み込むことで、コードの品質管理を自動化し、開発の効率を向上させることができます。

資料請求

RELATED POSTS 関連記事

一覧へ戻る