PhpStorm advanced metadata
Besides built-in “code awareness” capabilities, PhpStorm relies on external knowledge of code, which comes in the form of PHP stubs and the special advanced metadata files .phpstorm.meta.php.
While stubs cover the Standard PHP Library components and common extensions, .phpstorm.meta.php can be used for extending the PhpStorm functionality based on your own needs or project requirements. The basic metadata file is bundled inside the PHP stubs package and located inside the meta folder. You can create multiple meta files and place them anywhere within your project – PhpStorm will collect and merge all the information from them.
In metadata files, regular PHP code is used as a configuration means, which allows using the existing APIs to analyse it. The specific format is chosen to facilitate the existing editor features, such as code completion, navigation and usage search, refactorings, and so on.
expectedArguments directive instructs PhpStorm that a certain function accepts a certain set of arguments. The directive is specified by providing the function you are working with, the zero-based index of the argument, and the actual set of expected values, as follows:
When adding your own entries, keep the following in mind:
You need to provide the fully qualified name of the function or method so that PhpStorm resolves it correctly.
You can enumerate expected arguments via the comma
,or the pipe
|bitwise operator. The former is used for functions expecting a single value out of the set of values, while the latter is used for functions expecting a bit mask of constants, such as json_encode.
Let’s say you are implementing a Console command based on the symfony/console component. Sometimes there will be arguments that you want to pass to the command. In this example, a
Symfony\Component\Console\Command::configure() method is being implemented:
expectedArguments in place, you can advise PhpStorm to expect the
InputArgument::* constants here. To do this, add the following line to .phpstorm.meta.php:
Now, when you invoke code completion Ctrl+Space, the added constants are displayed in the suggestions list:
For some functions, the list of possible arguments’ values can be quite large. What’s more, different functions can accept the same sets of values. If you provide the list of expected arguments for such functions, the .phpstorm.meta.php file will grow excessively large. It will contain duplicate data, and the amount of work required to maintain it will also double.
To handle this, inside a .phpstorm.meta.php file, you can use two directives,
registerArgumentsSetaccepts two arguments: the arbitrary name of the set of arguments and the list of actual values contained in this set. Values are specified the same way as the list of expected arguments: depending on the function or method you are working with, you can enumerate them via the comma
,or the pipe
To register the set of arguments, specify the directive like this:registerArgumentsSet('argumentsSetName', ...argumentsList);
Having registered the single set of arguments, you can reference it from within
expectedArgumentsby using the
argumentsSetdirective:expectedArguments(functionName, 0, argumentsSet("argumentsSetName"));
ini_set functions both accepting the same set of php.ini directives.
You can register the set of arguments as follows:
After that, you can reference this set from within
expectedArguments both for
Expected return values
expectedReturnValues directive instructs PhpStorm, which values a certain function or method returns. The directive is specified similarly to expectedArguments: you provide it with a function and the set of actual values (such sets can also be registered via ArgumentsSet) as follows:
After a function is specified, PhpStorm will provide code completion for function and static method calls in conditional statements.
Let’s say you are executing an HTTP request with one of the available PSR-7-compatible clients, and as the result, you’ll get a
$response object of a class implementing
\Psr\Http\Message\ResponseInterface. Here you may want to check the status code and perform some suitable action. It may turn out handy to instruct PhpStorm that
ResponseInterface::getStatusCode() returns a set of HTTP status codes:
The factory design pattern is commonly used in PHP frameworks (such as Magento, Doctrine, Kohana, ZF2, and so on). By using a metadata file, you can implement generic support for the factory pattern in PhpStorm.
Suppose you have something like the following "service" or "helper" provider of interfaces/objects.
You can make the following cases operable by using the additional metadata file.
The .phpstorm.meta.php for this case should look as follows: