php - software - Cómo documentar los métodos magic(_call y_callStatic) para IDEs

plantilla para documentar codigo

Question

Después de muchos años felices de codificación en el bloc de notas ++ y sublime, me han aconsejado dar un IDE de PHP. Estoy probando phpStorm y parece agradable. La finalización del código y la documentación es una gran característica, pero no funciona para mí cuando se utilizan métodos mágicos. ¿Existe una solución alternativa para que phpStorm comprenda lo que sucede en los métodos mágicos?

Nuestra situación es algo como esto:

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();

El método magic callStatic nos permite obtener una colección de objetos a través de uno o más argumentos que conforman la llamada a la función.

Veo que hay una declaración @method para usar en estos casos, pero phpStorm solo está recogiendo la primera de estas afirmaciones. Además, solo puedo configurar el tipo de retorno en mixto, donde prefiero poder configurarlo como cualquier clase a la que se invocó (b en mi ejemplo).

Cualquier idea o sugerencia sería muy gratamente recibida, gracias.

Answer 1

Algo relacionado con la pregunta original:

También puede definir esto en el meta archivo phpstorm. Aquí hay un ejemplo para el método de fábrica (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();

De esta forma no tienes que bloquear todas las posibilidades cuando ocurre la magia.

Tenga algunos docs para más detalles.

Answer 2

Utilice el comentario PHPDoc a nivel de clase, específicamente @method tag, funciona bien en PhpStorm:

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

En lo de arriba:

• @method - Etiqueta PHPDoc
• static - dice que este es un método estático
• someClass o $this - tipo de devolución
• get_by_user_id - nombre del método
• (int $id) - firma de método: ([[type] [parameter]<, ...>])
• Bla-bla - alguna descripción opcional

Más sobre @method :

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

PD Mientras @method static funciona bien en PhpStorm (le dice a IDE que el método es estático) puede que no sea (¿todavía?) Compatible con la herramienta phpDocumentor actual (lo siento, no lo he usado por un tiempo).

Alternativamente : (en PhpStorm, por supuesto) Settings | Inspections | PHP | Undefined | Undefined method --> Downgrade severity if __magic methods are present in class Settings | Inspections | PHP | Undefined | Undefined method --> Downgrade severity if __magic methods are present in class Settings | Inspections | PHP | Undefined | Undefined method --> Downgrade severity if __magic methods are present in class - no ayudará con la finalización del código para tales métodos de ninguna manera, pero no marcará esos métodos mágicos como errores del "método indefinido".

Boleto de phpDocumentor sobre el uso de RegEx / nombres parciales para @property / @method tags (cómo puede ser útil para la documentación y qué poca ayuda puede aportar al IDE real cuando se trata de completar el código):

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