Introduction

¿Cansado del vago tipo callable de PHP? Es difícil entender qué espera realmente un parámetro de función. Esta guía demuestra cómo aprovechar PHPDoc para definir con precisión los parámetros callable, mejorando la claridad del código y permitiendo un análisis estático potente. Aprenderá a definir el número esperado de argumentos, tipos de retorno e incluso tipos de parámetros dentro de PHPDoc, lo que permitirá que herramientas como PHPStorm proporcionen una finalización automática precisa y detección de errores. ¡Refinemos sus sugerencias de tipo callable!

Problemas y Restricciones: Por qué PHPDoc para funciones es difícil en PHPStorm

Las capacidades de sugerencia de tipos de PHPStorm para parámetros invocables presentan un desafío debido a la flexibilidad inherente de los invocables en PHP. Definir la firma esperada de una función de retorno de llamada dentro de PHPDoc se vuelve complejo porque PHP permite una amplia gama de tipos de invocables válidos (clausuras, funciones anónimas, métodos, etc.). El IDE tiene dificultades para interpretar y hacer cumplir con precisión estas especificaciones de PHPDoc para parámetros invocables.

El problema surge de la tipificación laxa de PHP y la definición amplia de lo que constituye un invocable. PHPDoc puede describir los tipos de argumentos esperados del invocable, pero el IDE no siempre puede traducir esto en sugerencia de tipos estrictos o proporcionar finalización automática robusta para funciones pasadas como callbacks. Esto limita los beneficios de PHPDoc al proporcionar orientación clara y ejecutable para los desarrolladores.

En última instancia, si bien PHPDoc intenta clarificar la estructura esperada del callback, el soporte de PHPStorm para hacer cumplir con precisión estas especificaciones sigue siendo limitado debido al sistema de callable flexible de PHP. La interpretación del IDE de PHPDoc para callables es a menudo más sugestiva que prescriptiva.

<?php

class Foo {
    /**
     * @var ArrayObject[]
     */
    public $items = [];

    /**
     * Applies a callback to the items.
     *
     * @param callable $baz A callback that receives an ArrayObject of items.
     */
    public function bar(callable $baz): void {
        if (!is_callable($baz)) {
            throw new InvalidArgumentException('The provided argument is not callable.');
        }

        $items = new ArrayObject($this->items);
        call_user_func($baz, $items);
    }
}

// Example usage:
$foo = new Foo();
$foo->items[] = 'item1';
$foo->items[] = 'item2';

$foo->bar(function (ArrayObject $items) {
    foreach ($items as $item) {
        echo $item . "\n";
    }
});

Enfoques Existentes: @see con métodos estáticos, clases anónimas, trucos de interfaz

Las prácticas existentes de PHP para documentar las firmas de funciones de devolución de llamada dentro de los parámetros de los métodos históricamente han sido limitadas y a menudo dependían de soluciones alternativas. Los enfoques iniciales involucraron el uso de etiquetas @see junto con métodos estáticos, empleando clases anónimas o aprovechando trucos de interfaz para intentar comunicar el tipo de devolución de llamada esperado. Sin embargo, estos métodos a menudo resultaron engorrosos, carecían de precisión y no se integraron completamente con las capacidades modernas de sugerencia de tipos de IDE.

La necesidad de una documentación más clara surgió del deseo de permitir que los IDE, como PHPStorm, proporcionen sugerencias de tipos precisas para las funciones pasadas como devoluciones de llamada. Esto mejora la finalización de código, la detección de errores y la productividad general del desarrollador. El objetivo es permitir que un lector comprenda fácilmente la firma esperada —los parámetros de entrada y el tipo de retorno— de la función de devolución de llamada.

Al utilizar PHPDoc específicamente diseñado para documentar parámetros invocables, se puede lograr un enfoque más estandarizado y efectivo. Este método permite una definición precisa de los parámetros de entrada y el tipo de retorno de la devolución de llamada dentro del PHPDoc, lo que conduce a un mejor soporte de IDE y claridad del código.

<?php

/**
 * Class Foo
 */
class Foo {
    /**
     * @var array
     */
    public $items = [];

    /**
     * Executes a callback function with the items.
     *
     * @param callable $baz The callback function to execute.
     * @throws InvalidArgumentException If the provided parameter is not callable.
     */
    public function bar(callable $baz): void {
        if (!is_callable($baz)) {
            throw new InvalidArgumentException('The provided parameter must be callable.');
        }

        $items = new ArrayObject($this->items);
        $baz($items);
    }
}

// Example usage:
$foo = new Foo();
$foo->items = ['item1', 'item2', 'item3'];

$foo->bar(function (ArrayObject $items) {
    foreach ($items as $item) {
        echo $item . "\n";
    }
});

Solución Recomendada: Interfaz PHP 7+ + patrón de clase anónima para análisis estático

Para mejorar el análisis estático y el soporte de IDE al trabajar con funciones de retorno de llamada pasadas como parámetros, un enfoque recomendado utiliza el patrón de interfaz y clase anónima de PHP 7 o posterior. Esta estrategia permite una documentación más precisa de la firma de retorno de llamada esperada dentro de los comentarios PHPDoc. Al definir una interfaz, los parámetros y tipos de retorno esperados de la función de retorno de llamada se declaran explícitamente.

Esta interfaz se referencia entonces en el PHPDoc para el método que acepta la función de retorno de llamada. El patrón de clase anónima proporciona una forma de refinar aún más la firma documentada creando una clase que representa la estructura de la función de retorno de llamada esperada. Esto permite que los IDE proporcionen sugerencias y verificación de errores más precisos para el código que llama al método.

En última instancia, esta combinación promueve una mejor claridad del código, reduce los posibles errores y mejora la experiencia del desarrollador al aprovechar las características modernas de PHP para definir y documentar con precisión las expectativas de las funciones de devolución de llamada.

<?php

// Define an interface for the callback function
interface CallbackInterface {
    public function __invoke(ArrayObject $items);
}

class Foo {
    public $items = [];

    /**
     * @param CallbackInterface $baz A callback to receive the items
     */
    public function bar(CallbackInterface $baz) {
        $items = new ArrayObject($this->items);
        $baz($items);
    }
}

// Example usage:
$foo = new Foo();
$foo->items = [1, 2, 3];

// Define a callback using an anonymous class
$callback = new class implements CallbackInterface {
    public function __invoke(ArrayObject $items) {
        foreach ($items as $item) {
            echo $item . "\n";
        }
    }
};

// Call the bar method with the callback
$foo->bar($callback);

Conclusion

La definición de tipos para parámetros de funciones invocables en PHP sigue siendo un desafío, particularmente para el análisis estático dentro de IDEs como PHPStorm. Si bien soluciones existentes como @see y clases anónimas ofrecen soluciones alternativas, el enfoque recomendado aprovecha las interfaces de PHP 7+ combinadas con clases anónimas. Este patrón proporciona un método más limpio y robusto para representar con precisión los tipos invocables, mejorando la claridad del código y permitiendo un mejor análisis estático para una mayor productividad del desarrollador.