Corchetes angulares (<>) en PHPDoc

¿Qué es un "class-string" y para qué sirven los corchetes angulares "(<>)", que aparecen por ejemplo en el siguiente PHPDoc: @var class-string<\Illuminate\Database\Eloquent\Model> (código propio de Laravel)?

El PHPDoc @var class-string<\Illuminate\Database\Eloquent\Model> combina dos conceptos importantes para la legibilidad y el análisis de código: el tipo class-string y los "corchetes angulares" (<>) para tipos genéricos.

Vamos a desglosar cada parte.

---

1. ¿Qué es class-string?

El tipo class-string no es un tipo de dato nativo de PHP, sino una etiqueta especial de PHPDoc (introducida por herramientas como Psalm y PHPStan) para indicar que una variable contiene el nombre completo de una clase como una cadena de texto.

Por ejemplo:

• class-string sería el tipo de la variable $miClase = 'App\Models\User';

• El tipo string también funcionaría, pero class-string es mucho más específico y útil para el análisis estático.

Su función principal es decirles a las herramientas de análisis de código: "Este valor no es una simple cadena; es el nombre de una clase que realmente existe y puede ser usada".

---

2. ¿Qué son los Corchetes Angulares (< >)?

Los corchetes angulares en este contexto (< ... >) se utilizan para especificar un tipo genérico (generic type).

La sintaxis genérica es un concepto de la programación que permite escribir código que funciona con diferentes tipos de datos, pero el tipo específico se define en el momento de su uso. En el mundo de PHP, que no tiene genéricos nativos, los corchetes angulares son la forma estándar en los comentarios PHPDoc para simular este comportamiento.

En este caso, class-string<\Illuminate\Database\Eloquent\Model> le dice al analizador:

"Esta variable contiene el nombre de una clase como cadena de texto, y esa clase es un subtipo o implementa \Illuminate\Database\Eloquent\Model."

Es decir, la cadena de texto $miClase debe ser algo como 'App\Models\Post', 'App\Models\Product', etc., donde Post y Product son clases que extienden Illuminate\Database\Eloquent\Model.

---

Explicación Completa del PHPDoc

Juntando ambos conceptos, el PHPDoc @var class-string<\Illuminate\Database\Eloquent\Model> significa:

"La variable a la que se refiere este comentario (@var) es una cadena de texto que contiene el nombre de una clase. Además, esa clase debe ser del tipo Illuminate\Database\Eloquent\Model (o cualquier clase que la herede)."

¿Para qué sirve?

Principalmente, para mejorar el análisis estático y la autocompletación en tu IDE:

• Autocompletado inteligente: Si tu IDE sabe que $miClase es un class-string, al escribir $miClase::, te podrá sugerir métodos estáticos que pertenecen a \Illuminate\Database\Eloquent\Model.

• Detección de errores: Las herramientas como PHPStan pueden advertirte si intentas pasar una cadena como 'App\Services\SomeService' a una función que espera un class-string<\Illuminate\Database\Eloquent\Model>, ya que SomeService no hereda de Model.

En resumen, esta sintaxis de PHPDoc es una forma de proporcionar información de tipo mucho más precisa y detallada a las herramientas de análisis de código, lo que resulta en un código más robusto, seguro y fácil de mantener.

---

También veo otros usos de los corchetes angulares (<>) como por ejemplo "@return array<string, mixed>". ¿Qué sugiere acá?

La sintaxis con los corchetes angulares (<>) en PHPDoc es una herramienta para indicar tipos genéricos, pero su significado varía dependiendo del tipo de dato con el que se use.

En el caso de @return array<string, mixed>, los corchetes angulares no sugieren un tipo de subclase, sino que se usan para describir la estructura y los tipos de los elementos dentro del array.

Vamos a desglosarlo para que veas la diferencia:

---

PHPDoc de array<string, mixed>

Este PHPDoc se lee de la siguiente manera:

• array: El método va a devolver un tipo array.

• <string, mixed>: Los corchetes angulares especifican el tipo de datos que contiene ese array. La sintaxis es array<tipo_de_la_clave, tipo_del_valor>.

  • string: Indica que todas las claves del array serán cadenas de texto (strings).

  • mixed: Indica que los valores del array pueden ser de cualquier tipo de dato (números, cadenas, booleanos, objetos, etc.). mixed es un pseudo-tipo de PHPDoc que significa "cualquier tipo".

Por lo tanto, @return array<string, mixed> le dice a tu editor y a los analizadores estáticos que el método retornará un array asociativo con claves de tipo string y valores de cualquier tipo.

Comparación con @var class-string<Model>

Sintaxis PHPDoc	Tipo Base	Significado de <>	Ejemplo
array<string, mixed>	array	Describe la estructura interna (tipos de clave y valor).	El método retorna un array asociativo ['clave' => 'valor', ...]
class-string<Model>	class-string (una cadena de texto)	Describe una restricción o "subtipo" de la cadena de texto base.	La cadena de texto debe ser un nombre de clase que herede de Model.

Como puedes ver, aunque en ambos casos se usan corchetes angulares, su función es diferente:

• Con tipos contenedores como array o Collection, los corchetes angulares especifican los tipos de los elementos que contienen.

• Con pseudo-tipos como class-string, los corchetes angulares especifican una restricción o un "tipo de clase" que la cadena debe cumplir.

En ambos casos, la meta es la misma: proporcionar información de tipo más precisa a las herramientas de desarrollo para mejorar el autocompletado y la detección de errores en tu código.