Как документировать магические (_call и _callStatic) методы для IDE

Question

После многих счастливых лет написания кода в notepad++ и возвышенном, мне посоветовали попробовать PHP IDE. Я пробую phpStorm, и это кажется хорошим. Завершение кода и документация - отличная возможность, но у меня не получается, когда используются магические методы. Есть ли способ заставить phpStorm понять, что происходит в магических методах?

Наша ситуация примерно такая:

abstract class a {
    public static function __callStatic($method,$args)
    {
        if(strpos($method,"get_by_") === 0)
        {
            //do stuff
        } elseif(strpos($method,"get_first_by_") === 0) {
            //do stuff
        } elseif($method == "get_all") {
            //do stuff
        }
    }
}

class b extends a {
    // some more stuff
}

b::get_by_user_id(27);
b::get_first_by_id(156);
b::get_all();

Волшебный метод callStatic позволяет нам получить коллекцию объектов через 1 или более аргументов, составляющих вызов функции.

Я вижу, что в этих случаях есть оператор @method, но phpStorm выбирает только первое из этих утверждений. Кроме того, я могу только установить тип возвращаемого значения для смешанного, где я предпочел бы иметь возможность установить его как любой класс, к которому он был вызван (b в моем примере).

Любые идеи или предложения будут очень благодарны, спасибо.

Answer 1

Использование комментария PHPDoc на уровне класса - в частности, тега @method - отлично работает в PhpStorm:

/**
 * @method static someClass get_by_user_id(int $id) Bla-bla
 * @method static someClass get_first_by_id(int $id) 
 */
abstract class a {
...

В приведенном выше:

• @method - тег PHPDoc
• static - говорит, что это статический метод
• someClass или же $this - тип возврата
• get_by_user_id - название метода
• (int $id) - подпись метода: ([[type] [parameter]<, ...>])
• Bla-bla - некоторое дополнительное описание

Больше о @method:

• http://www.phpdoc.org/docs/latest/references/phpdoc/tags/method.html
• https://github.com/phpDocumentor/phpDocumentor2/blob/develop/docs/PSR.md#711-method

PS пока @method static прекрасно работает в PhpStorm (говорит IDE, что метод статический), он может (пока?) не поддерживаться реальным инструментом phpDocumentor (извините, не использовал его некоторое время).

---

В качестве альтернативы: (в PhpStorm, конечно) Settings | Inspections | PHP | Undefined | Undefined method --> Downgrade severity if __magic methods are present in class - это никак не поможет завершению кода для таких методов, но не пометит эти магические методы как ошибки "неопределенного метода".

---

билет phpDocumentor относительно использования RegEx/ частичных имен для @property/@method теги (как это может быть полезно для документации и как мало помощи она может принести реальной IDE при работе с завершением кода):

• https://github.com/phpDocumentor/phpDocumentor2/issues/689

Answer 2

Несколько связано с оригинальным вопросом:

Вы также можете определить это в метафайле phpstorm. Вот пример для фабричного метода (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();

Таким образом, вам не нужно блокировать каждую возможность, когда случается магия.

Есть некоторые документы для деталей.