はじめに

オープンワーク株式会社の23卒Webアプリエンジニアの室永です。入社から1年が経とうとしており時の流れの早さを痛感しています。さよなら、新卒1年目...

最近、次回バージョンアップに向け、現行バージョンでのdeprecation（非推奨コード）の一覧化を行ったのですが、phpstan-deprecation-rulesというツールが便利だったためそちらの紹介をしたいと思います。

github.com

phpstan-deprecation-rulesとは

PHPの静的解析ツールであるPHPStanの公式拡張パッケージです。

phpstan.org

通常のPHPStanと同様に任意ファイルに対し静的解析を行い、deprecationの利用箇所を検知してくれます。

なぜやったか

当社では定期的にPHPやSymfonyなどのバージョンアップを実施しています。

メジャーバージョンアップ（Symfony5.4 → Symfony6.0のような大規模な変更）を実施すると、現行のバージョンでdeprecationとなっている機能は削除され使えなくなることが多いです。いわゆる下位互換性のない変更というものですね。

よって、現行のバージョンでdeprecationとなっているコードは前もって対処することによって、次回バージョンアップ時のコストを減らすことが目的になります。この現行バージョンでのdeprecationコードを検知するために、phpstan-deprecation-rulesを利用しました。

当社でのバージョンアップ事例については以下の記事をご覧ください。

techblog.openwork.co.jp

使い方

インストール

Composerでインストールすることができます。

composer require --dev phpstan/phpstan-deprecation-rules

phpstan.neonの作成

任意箇所にconfigファイルのphpstan.neonを作成し、includesオプションにphpstan/phpstan-deprecation-rulesのパッケージパスを設定します。

また、その他オプション設定によって特定エラーを検知しないようにしたりすることができます。

includes:
    - vendor/phpstan/phpstan-deprecation-rules/rules.neon  // 適切なパスを設定する

parameters:
    level: 0
    ignoreErrors:
        - '#xxx#'

コマンド実行

以下のコマンドを実行することで任意ファイルのdeprecation利用箇所を検知できます。

// ./vendor/bin/phpstan analyse {解析対象のファイルパス} -c {phpstan.neonのファイルパス}
./vendor/bin/phpstan analyse src/sample.php -c config/phpstan.neon

PHPStanのコマンド同様、複数ファイルの一括実行も可能です。

./vendor/bin/phpstan analyse src/ -c config/phpstan.neon

トラブルシューティング

phpstan.neonなどに不備がないのにエラーが発生する場合、キャッシュクリアで実行できる場合があります。

./vendor/bin/phpstan clear

また、大量のファイルに対して一括実行する場合、以下のようにメモリ不足になってしまう可能性があります。

-- --------------------------------------------------------------------------------------------------- 
     Error                                                                                              
-- --------------------------------------------------------------------------------------------------- 
     Child process error: PHPStan process crashed because it reached configured PHP memory limit: xxxM  
     Increase your memory limit in php.ini or run PHPStan with --memory-limit CLI option.               
                                                                                                        
-- ---------------------------------------------------------------------------------------------------

その場合、--memory-limitオプションを付与することでメモリ上限を変更することが可能です。

./vendor/bin/phpstan analyse src/ -c config/phpstan.neon --memory-limit=2G

工夫したこと

特定エラーの除去

deprecation以外の特定エラーを無視するようにphpstan.neonに無視したいエラーを記述しました。正規表現も利用可能です。

    ignoreErrors:
        - '#Access to an undefined property [\s\S]*.#'
        - '#Access to undefined constant [\s\S]*.#'

外部ライブラリのdeprecationのみ検知

また、ライブラリ以外で独自定義した@deprecatedアノテーションを検知しないように、エディタの一括置換機能でプロジェクト内の該当アノテーションを一時的にすべて削除してから実行しました。

今回の目的は「バージョンアップ時のコスト削減」であり、あくまで次回バージョンアップで削除されてしまう外部ライブラリのdeprecationを一覧化したいという背景のためです。

GASで自動整形

最後に、GASで出力結果を整形し、Googleスプレッドシートに記載しました。手作業で整形すると大変なので、自動化可能な箇所はできるだけ自動化したいですね。

注意点

以下のように、deprecationの記述方法によっては検知できないケースがあります。

// アトリビュートを利用している
#[Deprecated(reason: 'xxx')]
public function xxx(): xxx
{
    // ...
}

// trigger_deprecationを利用している
trigger_deprecation('symfony/xxx', 'x.x', ...);

README.mdへの記述どおり、あくまで@deprecatedアノテーションの付いたコードの利用箇所を検知してくれるようです。 Issuesとしても取り上げられていました。

github.com

Symfonyフレームワークを利用しているのであれば、PHPUnit実行時に動的にdeprecationを検知してくれるPHPUnit Bridgeを併用するのも一つ考えられると思います。他にも良いツールがあるのであれば積極的に取り入れたいですね。

symfony.com