How to document magic (_call and _callStatic) methods for IDEs
Use class-level PHPDoc comment -- specifically @method tag -- works fine in PhpStorm:
/**
* @method static someClass get_by_user_id(int $id) Bla-bla
* @method static someClass get_first_by_id(int $id)
*/
abstract class a {
...
In the above:
@method
-- PHPDoc tagstatic
-- tells that this is static methodsomeClass
or$this
-- return typeget_by_user_id
-- method name(int $id)
-- method signature:([[type] [parameter]<, ...>])
Bla-bla
-- some optional description
More about @method
:
- https://docs.phpdoc.org/latest/references/phpdoc/tags/method.html
- https://github.com/phpDocumentor/phpDocumentor2/blob/develop/docs/PSR.md#711-method
P.S.
While @method static
works fine in PhpStorm (tells IDE that method is static) it may not be (yet?) supported by actual phpDocumentor tool (sorry, have not used it for a while).
Alternatively: (in PhpStorm, of course) Settings | Inspections | PHP | Undefined | Undefined method --> Downgrade severity if __magic methods are present in class
-- it will not help with code completion for such methods in any way, but will not mark those magic methods as "undefined method" errors.
phpDocumentor's ticket regarding using RegEx/partial names for @property
/@method
tags (how it can be useful for documentation and how little help it may bring to the actual IDE when dealing with code completion):
- https://github.com/phpDocumentor/phpDocumentor2/issues/689
Somewhat related to original question:
You can also define this in phpstorm meta file. Here's an example for factory method (v2016.3):
// Define in .phpstorm.meta.php
namespace PHPSTORM_META {
$STATIC_METHOD_TYPES = [
\Factory::create('') => [],
];
}
// Then use in code
$factory = new \Factory();
$user = $factory->create(\User::class);
// Here you get autocomplete.
$user->subscribe();
This way you don't have to docblock every possibility when magic happens.
Have some docs for details.