PhpStorm の高度なメタデータ

ビルトインの「コード認識」機能に加えて、PhpStorm は、 PHP スタブや特別な高度なメタデータファイルの形式で提供されるコードの外部知識に依存します。

スタブは標準 PHP ライブラリのコンポーネントや一般的な拡張機能をカバーしていますが、メタデータファイルを使って独自のニーズやプロジェクト要件に基づき PhpStorm の機能を拡張できます。基本的なメタデータファイル .phpstorm.meta.php は、PHP スタブパッケージ内にバンドルされており、 meta フォルダー内にあります。

プロジェクト内にメタデータファイルを作成する

以下のいずれかを行ってください：
- php ファイルを作成し、 .phpstorm.meta.php という名前を付けます。このようなファイルをいくつか作成して、プロジェクト内の異なる場所に保存できます。 PhpStorm は、それらからすべての情報を収集し、統合します。
- ディレクトリを作成し、 .phpstorm.meta.php という名前を付けます。このディレクトリ内に、任意の数のメタデータファイルを保存し、任意の名前を付けることができます。
メタファイル内で、 PHPSTORM_META 名前空間を宣言し、メタデータディレクティブを提供します。
namespace PHPSTORM_META { //metadata directives }
メタデータディレクティブは、特定の関数またはメソッドの処理方法を指定します。ディレクティブは通常の PHP コードとして記述されており、コード補完 Ctrl+Space、ナビゲーションと使用箇所の検索、リファクタリングなどの既存のコードエディター機能を使用できます。

メタデータディレクティブに移動する

expectedArguments、 exitPoint 、またはオーバーライドディレクティブを使って関数の動作が変更された場合、PhpStorm は関数宣言の横のエディターガターにアイコンを表示します。
アイコンをクリックして、メタファイル内の対応するディレクティブに移動します。

メソッドが受け入れる引数を定義する

expectedArguments ディレクティブは、特定の関数が特定の引数セットを受け入れることを PhpStorm に指示します。ディレクティブは、次のように、使用している関数、引数のゼロベースのインデックス、期待値の実際のセットを提供することによって指定されます。

expectedArguments(functionFQN, argumentIndex, ...argumentsList);

予想される引数は、コンマ , またはパイプ | ビット演算子(英語)を使用して列挙できます。前者は、値のセットから単一の値を期待する関数に使用され、後者は、 json_encode(英語) などの定数のビットマスクを期待する関数に使用されます。

例として、 symfony/console(英語) コンポーネントに基づいたコンソールコマンドを実装するとします。コマンドに渡す引数がある場合があります。この例では、 Symfony\Component\Console\Command::configure() メソッドが実装されています。

expectedArguments を設定すると、PhpStorm に対してここで InputArgument::* 定数を期待するように指示できます。これを行うには、メタデータファイルに次の行を追加します。

            expectedArguments(
                    \Symfony\Component\Console\Command\Command::addArgument(),
                    1,
                    \Symfony\Component\Console\Input\InputArgument::OPTIONAL,
                    \Symfony\Component\Console\Input\InputArgument::REQUIRED,
                    \Symfony\Component\Console\Input\InputArgument::IS_ARRAY
            );
        
  

ここで、コード補完 Ctrl+Space を呼び出すと、追加された定数が候補リストに表示されます。

可能な戻り値を定義する

expectedReturnValues ディレクティブは、特定の関数やメソッドがどの値を返すかを PhpStorm に指示します。このディレクティブは expectedArguments と同様に指定します。関数と実際の値のセット（こうしたセットは ArgumentsSet でも登録できます）を次のように設定します：

expectedReturnValues(functionFQN, ...argumentsList);

関数が指定されると、PhpStorm は条件ステートメントでの関数呼び出しや static メソッド呼び出しにコード補完を提供します。

例として、利用可能な PSR-7 互換クライアント(英語)のいずれかを使用して HTTP リクエストを実行し、その結果、 \Psr\Http\Message\ResponseInterface(英語) を実装するクラスの $response オブジェクトを取得するとします。その後、ステータスコードを確認し、適切なアクションを実行できます。 ResponseInterface::getStatusCode() が HTTP ステータスコードの設定を返すことを PhpStorm に指示すると便利な場合があります：

            namespace PHPSTORM_META {
                expectedReturnValues(\Psr\Http\Message\ResponseInterface::getStatusCode(),
                        \Symfony\Component\HttpFoundation\Response::HTTP_OK,
                        \Symfony\Component\HttpFoundation\Response::HTTP_BAD_REQUEST,
                        \Symfony\Component\HttpFoundation\Response::HTTP_INTERNAL_SERVER_ERROR
                );
            }
        
  

条件ステートメント内でコード補完 Ctrl+Space を呼び出すと、追加された定数が候補リストで使用できるようになります。

名前付き引数セットまたは戻り値を作成する

一部の関数では、可能な引数の値のリストが非常に大きくなる場合があります。さらに、異なる関数が同じ値のセットを受け入れることができます。このような関数に予想される引数のリストを提供すると、メタデータファイルが非常に大きくなります。また、重複するエントリが含まれ、それを維持するために必要な作業量も 2 倍になります。

これを処理するには、メタデータファイル内でディレクティブ registerArgumentsSet および argumentsSet を使用できます。 registerArgumentsSet ディレクティブは、引数設定の任意の命名とその設定に含まれる実際の値のリストという引数を受け取ります。値は expected arguments のリストと同じ方法で指定します。操作する関数やメソッドにより、コンマ , やパイプ | ビット演算子で列挙できます。

引数のセットを登録するには、次のようにディレクティブを指定します。

registerArgumentsSet('argumentsSetName', ...argumentsList);

単一の引数セットを登録したら、 argumentsSet ディレクティブを使用して expectedArguments 内からそれを参照できます。

expectedArguments(functionFQN, 0, argumentsSet('argumentsSetName'));

例として、 ini_get と ini_set 機能の両方が同じ php.ini ディレクティブ(英語)のセットを受け入れると考えてください。

引数のセットを次のように登録できます。

registerArgumentsSet('ini_values', ...iniValuesList);

これを実行すると、 ini_get と ini_set の両方について、 expectedArguments 内からこのセットを参照できます。

            expectedArguments(\ini_get(), 0, argumentsSet('ini_values'));
            expectedArguments(\ini_set(), 0, argumentsSet('ini_values'));

終了ポイントを定義する

exitPoint ディレクティブを使うことで、指定した関数が終了ポイントとして機能することを PhpStorm に明示的に指示できます。このような関数の呼び出しは、PHP の組み込みの exit(英語) 関数または die(英語) 関数の呼び出しと同様に、終了呼び出しとして扱われます。ディレクティブは次のように指定されます。

exitPoint(functionFQN( [optionalArguments] ));

optionalArguments には、文字列リテラルまたはクラス定数を指定できます。オプションの引数が指定されている場合、この引数を使用した関数呼び出しのみが終了ポイントとして扱われます。それ以外の場合、実行は通常どおり続行されます。

例として、次のコードサンプルを考えます。

            class Application {
                public function terminate($param) {
                    exit();
                }
                public function run() {
                    $this->terminate('foo');
                    echo "Hello";
                    $this->terminate('bar');
                    echo " world!";
                }
            }
        
  

terminate('bar') メソッド呼び出しを終了ポイントとしてマークするには、次の行をメタデータファイルに追加します。

exitPoint(Application::terminate('bar'));

その結果、 bar 引数を指定した 終了する 呼び出しは、終了ポイントとして機能します。 実行 メソッドの最後の行は到達不能として扱われます。

メソッドの戻り値の型を定義する

多くの場合、関数のコード自体に基づいて関数の戻り値の型を明確に推測することはできません。 オーバーライド ディレクティブを使用すると、指定した関数が指定された引数に基づいて特定の型のエンティティを返すことを PhpStorm に明示的に指示できます。

ディレクティブは次のように指定されます。

override(functionFQN, overrideDirective);

説明:

functionFQN は、関数またはクラスメソッドの完全修飾名です。 __get()、 __call()、 __callStatic() マジックメソッドもサポートされています。
overrideDirective は次のいずれかです。
- 型: 関数の戻り値の型を渡された引数の型に設定します。
- elementType: 渡された引数が配列の場合、関数の戻り値の型を配列に含まれる要素の型に設定します。
- マップ: 引数値と関数の戻り値の型の間に任意のマッピングを設定します。

引数の型を使用する

型 ディレクティブは、関数の戻り値の型が引数の型と一致することを PhpStorm に指示します。ディレクティブは次のように指定されます。

override(functionFQN, type(argumentIndex));

argumentIndex は、関数の戻り値の型として使用される型の引数のゼロから始まるインデックスです。

例として、次のコードサンプルを考えます。

                class A {
                    public function doActionA($a) {
                        return $a;
                    }
                }

                class B {
                    public function doActionB($b) {
                        return $b;
                    }
                }
            
   

最初は、この式および同様の式でコード補完を取得しません。

これに対処するには、次の行をメタデータファイルに追加します。

override(A::doActionA(0), type(0));

この方法で、 doActionA() メソッドの戻り値の型が最初の引数の型、つまり今回のケースでのクラス B と一致することを PhpStorm に指示します。対応するコード補完エントリが利用可能になります。

配列要素のタイプを使用する

elementType ディレクティブは、配列を引数として受け入れる関数に適用できます。ディレクティブは、関数の戻り値の型が配列に含まれる要素の型と一致することを PhpStorm に指示します。同じ型の要素を持つ配列に対してのみ機能することに注意してください。ディレクティブは次のように指定されます。

override(functionFQN, elementType(argumentIndex));

ここで、 argumentIndex は、要素の型が関数の戻り値の型として使用される配列を含む引数のゼロから始まるインデックスです。

例として、次のコードサンプルを考えます。

                class A {
                    public function doActionA($a) {
                        return $a;
                    }
                }

                class B {
                    public function doActionB($b) {
                        return $b;
                    }
                }

                $B1 = new B();
                $B2 = new B();

                $arrB = [$B1, $B2];
                
   

最初は、この式および同様の式でコード補完を取得しません。

これに対処するには、次の行をメタデータファイルに追加します。

override(A::doActionA(0), elementType(0));

この方法で、配列が doActionA() に渡された場合、このメソッドの戻り値の型は配列要素の型、つまりこの場合はクラス B に一致することを PhpStorm に指示します。対応するコード補完エントリが利用可能になります。

任意の型マッピングを提供する

マップ ディレクティブを使用すると、引数の値と関数の戻り値の型の間に任意のマッピングを設定できます。このディレクティブを使用すると、PhpStorm でファクトリパターンの汎用サポートを実装でき、一般的な PHP フレームワーク（Magento、Doctrine、Kohana、ZF2 など）を利用する際にコーディング支援を受けられます。ディレクティブは次のように指定されます。

                override(functionFQN, map([
                        key => value,
                    ...
                ]));
            
   

ここで、 キー は文字列リテラル、グローバル定数、クラス定数であり、 値 は ::class 定数またはパターンリテラルです。パターンリテラル内では、指定された引数のリテラル値に解決される @ シンボルを使用できます。共用体型(英語) 、つまり、パイプ | シンボルで区切られたいくつかの型を提供することもできます。

例として、次のコードサンプルを考えます。

                define('myConst', 'GlobalConstant');

                class Factory {
                    const classConstant = 'ClassConstant';

                    public function get($name) {
                        return $name;
                    }

                    public function __call($name, $arguments) {}
                }

                class AClass {
                    public function doActionA() {}
                }

                class BClass {
                    public function doActionB() {}
                }

                $result = (new Factory())->get();
            
   

マップ メタデータディレクティブを使うことで、渡される引数に応じて (new Factory())->get() の期待される戻り値の型を PhpStorm に指示できます。さらに、 __call() マジックメソッド経由で呼び出されるメソッドについても戻り値の型を指定できます。

文字列リテラルを渡す

"special" 文字列リテラルが渡されると、 \Exception のインスタンスが返されます。

                    override(\Factory::get(), map([
                        "special" => \Exception::class,
                    ]));
                
    

グローバル定数を渡す

myConst グローバル定数が渡されると、 AClass のインスタンスが返されます。

                    override(\Factory::get(), map([
                        \myConst => \AClass::class,
                    ]));
                
    

クラス定数を渡す

classConstant クラス定数が渡されると、 BClass のインスタンスが返されます。

                    override(\Factory::get(), map([
                        \Factory::classConstant => \BClass::class,
                    ]));
                
    

ルックアップパターンを使用する

@Class ルックアップパターンでは、 'A' リテラルが渡された場合は AClass を解決でき、 'B' が渡された場合は BClass を解決できます。

                    override(\Factory::get(), map([
                        '' => '@Class'
                    ]));
                
    

マジックメソッドの動的リターン型を作成する

@Class ルックアップパターンでは、 a() メソッドが呼び出された場合は AClass を解決でき、 b() が呼び出された場合は BClass を解決できます。

                    override(\Factory::__call(), map([
                        '' => '@Class'
                    ]));
                
    

共用体タイプを使用する

AClass|BClass 共用体型宣言により、 AClass と BClass の両方を解決できます。

                    override(\Factory::get(), map([
                        '' => 'AClass|BClass'
                    ]));
                
    

SQL 言語インジェクションでテーブル名の動的接頭辞を設定する

多くのコンテンツ管理システムおよびフレームワークは、アプリケーション構成レベルで定義されるテーブル接頭辞の使用をサポートしています。コードでは、テーブルの名前は SQL 文字列内の接頭辞マーカーで指定されます。アプリケーションのデータベース層がこれらの文字列を処理するとき、そのような名前は接頭辞を含む実際のテーブル名に置き換えられます。

sql_injection_subst メタデータディレクティブを使用することにより、挿入された SQL 文字列で接頭辞マーカーを実際の接頭辞に置き換えるためのルールを設定できます。その結果、PhpStorm はデータベーステーブルの命名にコード補完を提供し、 SQL クエリの実行時に利用します。

ディレクティブは次のように指定されます。

            override(sql_injection_subst(),
                map([
                    "prefix_marker" => "replacement"
                ]));
        
  

次の例を考えてみましょう。データベースには app_users と app_products テーブルがあり、 app_ テーブルプレフィックスが使われています。コード内では、 [prefix ] および #__ プレフィックスマーカーを使用してこれらのテーブルを参照します。最初は埋め込まれた SQL 文字列内のテーブルの命名が認識されないため、それらのコード補完は利用できません。

データベース接頭辞を登録するには、メタデータファイルに以下を追加します。

            override( sql_injection_subst(),
                map( [
                    "[prefix]" => "app_",
                    "#__" => "app_"
                ]));;
        
  

その結果、PhpStorm はプレフィックスマーカーを実際のプレフィックスに自動で置き換え、テーブルの命名が利用可能になります：

レガシーメタデータ形式 (非推奨)

            namespace PHPSTORM_META {
                $STATIC_METHOD_TYPES = [         // we make sections for scopes
                    \ServiceLocatorInterface::get('') => [   // STATIC call key to make static (1) & dynamic (2) calls work
                        "special" instanceof \Exception,   // "KEY" instanceof Class maps KEY to Class
                    ],
                    new \ServiceLocatorInterface => [ // NEW INSTANCE is to make ArrayAccess (3) style factory work
                        "special" instanceof \Exception,
                    ],
                    \ServiceLocatorInterface::getByPattern('') => [
                        "" == "@Iterator",    // "ignored" == "PatternWith@" substitutes @ with arg value
                    ],
                    \globalFactoryFunction('') => [   // (4) works also with functions
                    ],              // if key is not found its used as type name in all cases
                ];
            }
            
  

2026 年 5 月 22 日