Laravel 11 の PHP ジェネリック

Laravel を使用した Web アプリケーションビルダーで、静的コード分析に PHPStan を使用している場合、Laravel 11.x.

PHPStan を使用して Laravel を新規インストールすると、初めて ./vendor/bin/phpstan を実行すると、次のエラーがスローされます:

 ------ -----------------------------------------------------------------------------------
  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
 ------ -----------------------------------------------------------------------------------

それでは何が変わったのでしょうか？ Laravel 11 では、HasFactory トレイトに、予約されたジェネリックタグの 1 つである @template タグを持つ

PHPDoc が追加されました。すでにご想像のとおり、ジェネリックはフレームワークの多くの部分で使用されています。

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

推奨されませんが、次のコード行を phpstan.neon ファイルに追加するだけで、このカテゴリのエラーを無視できます。

parameters:
    ignoreErrors:
        -
            identifier: missingType.generics

しかし、ジェネリックはそれほど難しくないので、始めてみましょう!

ジェネリックとは何ですか?

プログラミングにおけるジェネリックとは、複数のデータ型を処理できるコードを作成できるようにする機能を指します。データ型ごとに個別のコードを記述する代わりに、混合型やオブジェクトなどの一般的な型を使用するのとは異なり、型の安全性を維持しながらさまざまな型を操作できる単一の汎用コードを記述することができます。

Laravel 10 の IlluminateDatabaseConcernsBuildsQueries::first メソッドを使用すると、Model のインスタンス、一般オブジェクト、IlluminateDatabaseEloquentBuilder や 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();
}

ジェネリック構文

ジェネリックは PHP では第一級市民としてサポートされていません。ジェネリックを使用するには、

PHPDocs タグ @template、@template-covariant、@template-contravariant、@extends、@implements、および@use.

ジェネリック型のルールは、

型パラメータを使用して定義されます。 PHPDocs では、それらに @template タグの注釈を付けます。既存のクラス名を使用しない限り、型パラメータ名は任意の名前にすることができます。 of キーワードを使用して、type パラメーターの代わりに使用できる型を上限で制限することもできます。これは有界型パラメータと呼ばれます。

<?php

namespace Illuminate\Database\Eloquent;

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

PHP ジェネリックの種類

汎用関数

ジェネリック関数は通常の関数とまったく同じですが、型パラメーターがあります。これにより、ジェネリック メソッドをより一般的な方法で使用できるようになります。

例として IlluminateSupportValidatedInput::enum メソッドを取り上げます。

• 型パラメータ TEnum を定義します。

• $enumClass パラメータは疑似型クラス文字列であり、同じ型パラメータ TEnum にバインドされています。

• 戻り値の型は TEnum または 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
 ------ -----------------------------------------------------------------------------------

$request→validated()→enum(‘status‘, OrderStatus::class) を呼び出すと、PHPStan は OrderStatus オブジェクトまたは null を取得していることを認識します!

汎用クラス

ジェネリック クラスを使用すると、型の安全性を確保しながら、任意のデータ型を操作できるクラスを作成できます。これにより、特定の型のプレースホルダーを使用してクラスを定義できるようになり、後でクラスがインスタンス化されるときに置き換えることができます。

Laravel ソース コードの良い例は、IlluminateDatabaseEloquentBuilder クラスです。

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

型パラメーター TModel が定義され、IlluminateDatabaseEloquentModel のサブクラスにバインドされます。同じ型パラメータが make.

メソッドの戻り値の型として使用されます。

もう 1 つの例は、ステータスに基づいて注文をフィルターするローカル スコープを持つ注文モデルがある場合です。スコープ メソッドでは TModel タイプを指定する必要があります

parameters:
    ignoreErrors:
        -
            identifier: missingType.generics

ℹ️ info: BelongsTo や HasOne などの名前空間 IlluminateDatabaseEloquentRelations 内のすべての Eloquent リレーション クラスが汎用になりました。

汎用インターフェース

汎用インターフェースはそれほど変わりません。 IlluminateContractsSupportArrayable は汎用インターフェイスの例です

/**
 * 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();
}

インターフェイスは、配列キー型の TKey (int または string にすることができます) と TValue という 2 つの型パラメーターを定義します。これら 2 つのパラメーターは、toArray 関数の戻り値の型を定義するために使用されます。以下に例を示します:

<?php

namespace Illuminate\Database\Eloquent;

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

ユーザー クラスは Arrayable インターフェイスを実装し、Tkey タイプを int として指定し、TValue を文字列として指定します。

一般的な特性

この投稿の冒頭のエラーで IlluminateDatabaseEloquentFactoriesHasFactory トレイトに遭遇しました。詳しく見てみましょう:

/**
 * @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));
}

HasFactory は、IlluminateDatabaseEloquentFactoriesFactory のサブクラスにバインドされた型パラメーター TFactory を定義します。では、そのエラーはどうすれば修正できるのでしょうか?

トレイトを使用する場合は、TFactory タイプを指定する必要があります。したがって、HasFactory トレイトの use ステートメントには、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);
    }
}

汎用性の維持

クラスを拡張するとき、インターフェースを実装するとき、またはトレイトを使用するときに、サブクラスの汎用性を維持することができます。

ジェネリック性の維持は、子クラスの上に同じ型パラメータを定義し、それを @extends、@implements、および @use タグに渡すことによって実装されます。

例として IlluminateDatabaseConcernsBuildsQueries 汎用特性を使用します。

型パラメータ 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
 ------ -----------------------------------------------------------------------------------

IlluminateDatabaseEloquentBuilder クラスはこの特性を使用しますが、TModel パラメーター タイプを渡すことで汎用性を維持します。 TModel のタイプ、したがって BuildsQueries トレイトの TValue の指定は、クライアント コードに委ねられるようになりました。

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

最終的な考え

結論として、PHP は他のプログラミング言語と同じようにジェネリックをネイティブにサポートしていませんが、PHPStan のような高度な型ヒントとツールの導入により、開発者はジェネリックのような機能をコードに実装できます。 。 PHPDocs、パラメーター化されたクラス、インターフェイスを活用することで、コードの再利用性と保守性を促進する、より柔軟でタイプセーフなアプリケーションを作成できます。 PHP が進化し続けるにつれて、コミュニティでは型安全性と静的解析に対する注目が高まっており、ジェネリックスを実装するためのより堅牢なソリューションが生まれる可能性があります。これらの実践を取り入れることは、コーディング スキルを向上させるだけでなく、時の試練に耐える高品質のソフトウェアの開発にも貢献します。

以上がLaravel 11 の PHP ジェネリックの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。