Génériques PHP dans Laravel 11

Si vous êtes un créateur d'applications Web avec Laravel et que vous utilisez PHPStan pour l'analyse de code statique, vous commencerez à voir de nouvelles erreurs lors de la mise à niveau vers Laravel 11.x.

Dans une nouvelle installation de Laravel avec PHPStan, lors de la première exécution de ./vendor/bin/phpstan, l'erreur suivante est générée :

 ------ -----------------------------------------------------------------------------------
  Line   app\Models\User.php
 ------ -----------------------------------------------------------------------------------
  13     Class App\Models\User uses generic trait
         Illuminate\Database\Eloquent\Factories\HasFactory but does not specify its types:
         TFactory
 ------ -----------------------------------------------------------------------------------

Alors, qu’est-ce qui a changé ? Dans Laravel 11, le trait HasFactory possède désormais un PHPDoc avec la balise @template qui est l'une des balises génériques réservées. Comme vous l'avez peut-être déjà deviné, les génériques sont utilisés dans de nombreuses parties du framework.

/**
 * @template TFactory of \Illuminate\Database\Eloquent\Factories\Factory
 */
trait HasFactory
{
    ...
}

Bien que cela ne soit pas recommandé, cette catégorie d'erreurs peut être ignorée en ajoutant simplement ces lignes de code à votre fichier phpstan.neon :

parameters:
    ignoreErrors:
        -
            identifier: missingType.generics

Mais les génériques ne sont pas si difficiles à comprendre, alors commençons !

Que sont les génériques ?

Les génériques en programmation font référence à une fonctionnalité qui vous permet d'écrire du code pouvant fonctionner avec plusieurs types de données. Au lieu d'écrire du code séparé pour chaque type de données, vous pouvez écrire un seul morceau de code générique qui peut fonctionner sur différents types tout en maintenant la sécurité des types, contrairement à l'utilisation de types généraux comme mixtes ou objets.

Prenez la méthode IlluminateDatabaseConcernsBuildsQueries::first de Laravel 10, elle peut renvoyer une instance de Model, un objet général, une instance de la classe l'utilisant comme IlluminateDatabaseEloquentBuilder ou null.

/**
 * Execute the query and get the first result.
 *
 * @param  array|string  $columns
 * @return \Illuminate\Database\Eloquent\Model|object|static|null
 */
public function first($columns = ['*'])
{
    return $this->take(1)->get($columns)->first();
}

Syntaxe générique

Les génériques ne sont pas pris en charge en PHP en tant que citoyen de première classe, pour les avoir, nous utilisons les balises PHPDocs @template, @template-covariant, @template-contravariant, @extends, @implements et @use.

Les règles des types génériques sont définies à l'aide de paramètres de type. Dans PHPDocs nous les annotons avec la balise @template . Le nom du paramètre de type peut être n’importe quoi, tant que vous n’utilisez pas de nom de classe existant. Vous pouvez également limiter les types pouvant être utilisés à la place du paramètre type avec une limite supérieure à l'aide du mot-clé of. C'est ce qu'on appelle paramètre de type borné.

<?php namespace Illuminate\Database\Eloquent;

/**
 * @template TModel of \Illuminate\Database\Eloquent\Model
 *
 */
class Builder implements BuilderContract
{
}

Types de génériques PHP

Fonction générique

Une fonction générique est exactement comme une fonction normale, cependant, elle a des paramètres de type. Cela permet d'utiliser la méthode générique de manière plus générale.

Prenons la méthode IlluminateSupportValidatedInput::enum comme exemple :

• Il définit un paramètre de type TEnum.

• Le paramètre $enumClass est du pseudo type classe-chaîne et délimité au même paramètre de type TEnum.

• Le type de retour peut également être TEnum ou null.
  

 ------ -----------------------------------------------------------------------------------
  Line   app\Models\User.php
 ------ -----------------------------------------------------------------------------------
  13     Class App\Models\User uses generic trait
         Illuminate\Database\Eloquent\Factories\HasFactory but does not specify its types:
         TFactory
 ------ -----------------------------------------------------------------------------------

Si vous appelez ensuite $request→validated()→enum('status', OrderStatus::class), PHPStan saura que vous obtenez un objet OrderStatus ou null !

Classe générique

Les classes génériques permettent de créer des classes capables de fonctionner sur n'importe quel type de données tout en garantissant la sécurité des types. Ils permettent de définir une classe avec un espace réservé pour un type spécifique, qui peut ensuite être remplacé lorsque la classe est instanciée.

Un bon exemple du code source de Laravel serait la classe IlluminateDatabaseEloquentBuilder :

/**
 * @template TFactory of \Illuminate\Database\Eloquent\Factories\Factory
 */
trait HasFactory
{
    ...
}

Un paramètre de type TModel est défini et lié à n'importe quelle sous-classe de IlluminateDatabaseEloquentModel. Le même paramètre de type est utilisé comme type de retour de la méthode make.

Un autre exemple serait si nous avions un modèle de commande, qui a une portée locale pour filtrer les commandes en fonction de leur statut. La méthode scope doit spécifier le type de TModel

parameters:
    ignoreErrors:
        -
            identifier: missingType.generics

ℹ️ info : Toutes les classes de relations Eloquent dans l'espace de noms IlluminateDatabaseEloquentRelations comme BelongsTo et HasOne sont désormais génériques.

Interface générique

Les interfaces génériques ne sont pas si différentes. L'IlluminateContractsSupportArrayable est un exemple d'interface générique

/**
 * Execute the query and get the first result.
 *
 * @param  array|string  $columns
 * @return \Illuminate\Database\Eloquent\Model|object|static|null
 */
public function first($columns = ['*'])
{
    return $this->take(1)->get($columns)->first();
}

L'interface définit deux paramètres de type : TKey de type array-key (il peut s'agir d'un entier ou d'une chaîne) et TValue. Ces deux paramètres permettent de définir le type de retour de la fonction toArray. Voici un exemple :

<?php namespace Illuminate\Database\Eloquent;

/**
 * @template TModel of \Illuminate\Database\Eloquent\Model
 *
 */
class Builder implements BuilderContract
{
}

La classe utilisateur implémente l'interface Arrayable et spécifie le type Tkey sous la forme d'un int et la TValue sous la forme d'une chaîne.

Caractère générique

Nous sommes tombés sur le trait IlluminateDatabaseEloquentFactoriesHasFactory dans l'erreur au début de cet article. Regardons de plus près :

/**
 * @template TEnum
 *
 * @param string $key
 * @param class-string<tenum> $enumClass
 * @return TEnum|null
 */
public function enum($key, $enumClass)
{
    if ($this->isNotFilled($key) ||
        ! enum_exists($enumClass) ||
        ! method_exists($enumClass, 'tryFrom')) {
        return null;
    }
    return $enumClass::tryFrom($this->input($key));
}
</tenum>

HasFactory définit un paramètre de type TFactory délimité aux sous-classes de IlluminateDatabaseEloquentFactoriesFactory. Alors, comment cette erreur peut-elle être corrigée ?

Le type TFactory doit être spécifié lorsque le trait est utilisé. Ainsi, l'instruction use du trait HasFactory doit être annotée avec le PHPDocs @use:

<?php namespace Illuminate\Database\Eloquent;
/**
 * @template TModel of \Illuminate\Database\Eloquent\Model
 */
class Builder implements BuilderContract
{
    /**
     * @param  array  $attributes
     * @return TModel
     */
    public function make(array $attributes = [])
    {
        return $this->newModelInstance($attributes);
    }
}

Préserver le caractère générique

Lors de l'extension d'une classe, de l'implémentation d'une interface ou de l'utilisation d'un trait, il est possible de conserver le caractère générique de la sous-classe.

La préservation du caractère générique est implémentée en définissant les mêmes paramètres de type au-dessus de la classe enfant et en les transmettant aux balises @extends, @implements et @use.

Nous utiliserons le trait générique IlluminateDatabaseConcernsBuildsQueries comme exemple,

il définit un paramètre de type TValue :

 ------ -----------------------------------------------------------------------------------
  Line   app\Models\User.php
 ------ -----------------------------------------------------------------------------------
  13     Class App\Models\User uses generic trait
         Illuminate\Database\Eloquent\Factories\HasFactory but does not specify its types:
         TFactory
 ------ -----------------------------------------------------------------------------------

La classe IlluminateDatabaseEloquentBuilder utilise ce trait mais conserve son caractère générique en lui passant le type de paramètre TModel. Il appartient désormais au code client de spécifier le type de TModel et par conséquent TValue dans le trait BuildsQueries.

/**
 * @template TFactory of \Illuminate\Database\Eloquent\Factories\Factory
 */
trait HasFactory
{
    ...
}

Pensées finales

En conclusion, bien que PHP ne prenne pas en charge nativement les génériques de la même manière que certains autres langages de programmation, l'introduction d'astuces et d'outils de type avancés comme PHPStan permet aux développeurs d'implémenter des fonctionnalités de type générique dans leur code. . En tirant parti de PHPDocs, des classes paramétrées et des interfaces, vous pouvez créer des applications plus flexibles et plus sécurisées qui favorisent la réutilisabilité et la maintenabilité du code. À mesure que PHP continue d'évoluer, l'attention croissante de la communauté sur la sécurité des types et l'analyse statique conduira probablement à des solutions plus robustes pour l'implémentation de génériques. L'adoption de ces pratiques améliore non seulement vos compétences en codage, mais contribue également au développement de logiciels de haute qualité qui résistent à l'épreuve du temps.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!