Upgrade Status
非推奨APIの使用状況をスキャンし、サイト環境とコンポーネントのDrupalメジャーアップグレード準備状況を確認します。
upgrade_status
インストール
composer require 'drupal/upgrade_status:^4.3'
概要
Upgrade Statusは、Drupalサイトのコードベースをスキャンして、次のDrupalメジャーバージョンとの互換性の問題を特定する包括的な開発者ツールです。インストールされているContribモジュール、カスタムモジュール、テーマ、プロファイルを分析し、アップグレード前に置き換える必要がある非推奨コードを検出します。
このモジュールは、mglaman/phpstan-drupal拡張機能を備えたPHPStanを使用して静的コード解析を実行し、Twigテンプレート、CSSセレクタ、ライブラリ定義、ルーティングファイル、テーマ関数、拡張機能メタデータ用の専門的なアナライザーも組み合わせて使用します。結果は重大度と次のアクションステップによって分類され、開発者がアップグレード作業の優先順位を付けるのに役立ちます。
Upgrade StatusはDrupalのUpdateモジュールと統合して、Contribプロジェクトの利用可能な更新を表示し、それらの更新が次のDrupalメジャーバージョンと互換性があるかどうかを示します。関係者とレポートを共有するためのHTMLおよびASCII形式でのエクスポートをサポートし、CI/CD統合用のDrushコマンドを提供します。
Features
- PHPStanベースの静的コード解析を実行し、モジュール、テーマ、プロファイル内の非推奨PHP APIの使用を検出
- Twigテンプレートの非推奨な構文とフィルター（spacelessタグなど）を解析
- CSSファイルの非推奨セレクター（例：#drupal-off-canvas）をスキャン
- ライブラリ定義（*.libraries.yml）の非推奨ライブラリ依存関係をチェック
- ルーティングファイルの非推奨ルート要件（例：_access_node_revision、_access_media_revision）を検証
- 非推奨テーマ関数の使用とオーバーライドを検出（Drupal 9/10で削除）
- 拡張機能メタデータ（*.info.yml）の欠落または非互換なcore_version_requirementを検証
- Viewsの設定における非推奨設定（例：default_argument_skip_url）をチェック
- PHP版、データベースの種類/バージョン、JSONサポート、Drushバージョンを含むDrupal 10、11、12の環境互換性チェックを提供
- 推奨される次のステップでプロジェクトを分類：未インストールの削除、更新の利用可能、スキャンが必要、メンテナーとの協力、Rectorで修正、手動で修正、または互換性あり
- ディレクトリ構造またはComposer/Gitデプロイメタデータに基づいてカスタムプロジェクトとContribプロジェクトを区別
- Updateモジュールと統合して、利用可能なプロジェクト更新と次のメジャーバージョン互換性を表示
- アップグレード準備状況のパーセンテージを示す視覚的な進捗インジケーターを表示
- スキャン結果をダウンロード可能なHTMLまたはASCIIテキストファイルとしてエクスポート
- プロジェクトごとの詳細なスキャン結果をモーダルダイアログで表示
- PHPの致命的エラーを適切に処理するためのHTTPサンドボックスを使用したバッチ処理をサポート
- 複数の出力形式（プレーン、checkstyle XML、Code Climate JSON）でコマンドライン分析とCI/CD統合用のDrushコマンドを含む
- バージョンと削除タイムラインに基づいて、非推奨を「今すぐ修正」「後で修正」「Rectorで修正可能」「無視」に分類
- 自動修正用のdrupal-rectorでカバーされる非推奨を検出
Use Cases
Drupal 10から11へのアップグレード準備
Drupal 10から11にアップグレードする前に、管理 > レポート > Upgrade statusに移動します。まず環境チェックを確認して、ホスティングがD11の要件（PHP 8.3以上、MySQL 8.0以上/MariaDB 10.6以上/PostgreSQL 16以上、Drush 13以上）を満たしていることを確認します。次に、すべてのプロジェクトを選択し、「選択項目をスキャン」をクリックしてコードベースを解析します。分類された結果を確認します：最初に利用可能な更新があるプロジェクトを更新し、次にカスタムコードの非推奨に対処します。「Rectorで修正」とマークされたプロジェクトは、drupal-rectorを使用して自動修正できます。結果をHTMLでエクスポートしてチームや関係者と共有します。
継続的インテグレーションでの非推奨チェック
Drushコマンドを使用してCI/CDパイプラインにUpgrade Statusスキャンを追加します。'drush upgrade_status:analyze --all --ignore-uninstalled --format=codeclimate > gl-code-quality-report.json'を実行して、GitLab CI互換のCode Climateレポートを生成します。Jenkinsやその他のCIシステムでは、'--format=checkstyle'を使用して静的解析ツールと互換性のあるXML出力を生成します。非推奨が見つかった場合にコマンドが失敗（終了コード > 0）するように設定して、非推奨APIの使用を導入するマージをブロックします。
Contribモジュールの互換性監査
新しいプロジェクトのためにContribモジュールを評価する際、Upgrade Statusを使用して将来のDrupalバージョンとの互換性を確認します。候補モジュールをインストールし、スキャンを実行して、どのモジュールが既に互換性があるか、どのモジュールに更新が必要か、どのモジュールにメンテナーとの協力が必要かを確認します。これにより、モジュール選択の優先順位付けと、プロジェクト計画の早い段階でのアップグレードブロッカーの特定に役立ちます。
Rectorで修正可能な非推奨の特定
多くの非推奨がある大規模なコードベースでは、Upgrade Statusを使用してどの問題を自動的に修正できるかを特定します。「Rectorで修正」として分類されたプロジェクトには、drupal-rectorルールでカバーされる非推奨が含まれています。'drush upgrade_status:analyze mycustommodule'を実行してモジュールをスキャンし、drupal/rectorをインストールして'vendor/bin/rector process web/modules/custom/mycustommodule'を実行して自動的に修正を適用します。修正が正しく適用されたことを確認するために再スキャンします。
関係者向けレポートの生成
すべてのプロジェクトを選択し、「選択項目をHTMLでエクスポート」をクリックして、プロジェクトマネージャーやクライアント向けの専門的なレポートを生成します。エクスポートされたHTMLファイルには、プロジェクトタイプ（カスタム vs. Contrib）別に整理されたすべての非推奨の完全なサマリーが含まれ、修正の緊急度が明確に分類されています。ターミナル出力を好む技術チームには、「選択項目をテキストでエクスポート」を使用して、メールやドキュメントに含めることができるASCIIレポートを生成します。
Tips
- アップグレードの準備がまだできていなくても、現在のDrupalバージョンでUpgrade Statusを実行して、早期にアップグレード準備を開始してください
- 「今すぐ」カテゴリの非推奨の修正を最初に行ってください - これらは直近の次のメジャーバージョンで削除されます
- スキャン前にContribモジュールを更新してください - 新しいバージョンには多くの場合、非推奨の修正が含まれています
- 修正を繰り返す際にキャッシュされた結果を再利用するには、--skip-existingオプションを使用してDrushコマンドを使用してください
- 「Rectorで修正」カテゴリは、drupal-rectorが修正を自動化できることを示しています - 大規模なコードベースでは使用を検討してください
- 「メンテナーとの協力」カテゴリで、貢献できるdrupal.orgのイシューやパッチを確認してください
- 非推奨を修正する前後にレポートをエクスポートして、進捗を追跡し、完了した作業を示してください
- 正確な環境チェックのために、本番環境と同じPHPバージョンとデータベースで実行していることを確認してください
Technical Details
Admin Pages 2
/admin/reports/upgrade-status
次のDrupalメジャーバージョンへのサイトの準備状況に関する包括的な情報を表示するメインのアップグレードステータスレポートページです。現在のDrupalバージョンに応じて、動的に「Drupal 10アップグレードステータス」「Drupal 11アップグレードステータス」「Drupal 12アップグレードステータス」を表示します。
/admin/reports/upgrade-status/project/{project_machine_name}
モーダルダイアログで単一プロジェクトの詳細なスキャン結果を表示します。検出されたすべての非推奨がカテゴリ別に整理され、ファイルパス、行番号、推奨される修正が表示されます。
権限 1
Hooks 2
hook_upgrade_status_operations_alter
プロジェクトのスキャン時に実行されるバッチ操作を変更できます。Rectorの実行などの追加処理を追加するのに便利です。
hook_upgrade_status_result_alter
特定のプロジェクトと結果グループのレンダリングされた結果表示を変更できます。カスタム情報の追加や説明の変更に便利です。
Drush Commands 2
drush upgrade_status:analyze
プロジェクトの非推奨を解析し、結果を出力します。CI/CD統合を含むさまざまなユースケース向けに複数の出力形式をサポートしています。
drush upgrade_status:checkstyle
非推奨。プロジェクトを解析し、checkstyle XML形式で結果を出力します。代わりに'drush upgrade_status:analyze --format=checkstyle'を使用してください。
Troubleshooting 6
Composerを使用してモジュールをインストールしたことを確認してください：'composer require drupal/upgrade_status'。このモジュールにはPHPStanとphpstan-drupalが必要で、これらはComposer経由でのみインストールされます。composer.jsonでカスタムのbin-dirやvendor-dirを使用している場合、モジュールは自動的にこれらの場所を検出します。
--phpstan-memory-limitオプションを使用してDrushでPHPStanのメモリ制限を増やします：'drush upgrade_status:analyze --phpstan-memory-limit=2G mymodule'。Webベースのスキャンでは、php.iniでPHPのmemory_limitを増やすことを検討してください。
モジュールはスキャン中のPHP致命的エラーを分離するためにHTTPリクエストを使用します。一部のコンテナやリバースプロキシ設定では失敗する可能性があります。サイトが自身にHTTPリクエストを行えることを確認してください。組み込みPHPサーバー（php -S）を使用している場合、並行リクエストをサポートしていないため、HTTPサンドボックスは自動的に無効になります。
まずDrupalの更新チェックを実行します：管理 > レポート > 利用可能な更新 > 手動でチェックに移動するか、'drush pm:security'を実行して更新情報を更新します。その後、Upgrade Statusに戻ると更新された互換性データが表示されます。
Composer管理サイトにはComposer Deploy（drupal/composer_deploy）を、Gitデプロイサイトにはにはにはには Git Deploy（drupal/git_deploy）をインストールしてください。これらのモジュールは、ディレクトリ構造のヒューリスティックではなく、デプロイメタデータに基づいて正確なプロジェクト識別を提供します。
モジュールは次のメジャーバージョンの後に削除される非推奨を自動的に「無視」に分類します。たとえば、Drupal 13で削除される非推奨は、Drupal 11へのアップグレード時には無視されます。削除タイムラインを理解し、将来のアップグレードに応じて計画するために、完全な非推奨メッセージを確認してください。
Security Notes 4
- このモジュールには「ソフトウェア更新の管理」パーミッションが必要で、これは通常、信頼された管理者に限定されます
- スキャン結果はDrupalのkey-valueストレージに保存され、セッション間で永続化されます
- モジュールはバッチ処理中にPHP致命的エラーを分離するために自身にHTTPリクエストを行います - ファイアウォールがlocalhostリクエストを許可していることを確認してください
- エクスポートされたHTML/ASCIIレポートには、サーバーのディレクトリ構造を明らかにするファイルパスが含まれる場合があります - エクスポートは内部ドキュメントとして扱ってください