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

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

 ------ -----------------------------------------------------------------------------------
  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 ファイルに追加するだけで、このカテゴリのエラーを無(wú)視できます。

parameters:
    ignoreErrors:
        -
            identifier: missingType.generics

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

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

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

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

ジェネリック構(gòu)文

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

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 ジェネリックの種類

汎用関數(shù)

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

例として 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 を取得していることを認(rèn)識(shí)します!

汎用クラス

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

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

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

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

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

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

parameters:
    ignoreErrors:
        -
            identifier: missingType.generics

?? info: BelongsTo や HasOne などの名前空間 IlluminateDatabaseEloquentRelations 內(nèi)のすべての 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 関數(shù)の戻り値の型を定義するために使用されます。以下に例を示します:

<?php

namespace Illuminate\Database\Eloquent;

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

ユーザー クラスは Arrayable インターフェイスを?qū)g裝し、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 を定義します。では、そのエラーはどうすれば修正できるのでしょうか?

トレイトを使用する場(chǎng)合は、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);
    }
}

汎用性の維持

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

ジェネリック性の維持は、子クラスの上に同じ型パラメータを定義し、それを @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
{
    ...
}

最終的な考え

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

以上がLaravel 11 の PHP ジェネリックの詳細(xì)內(nèi)容です。詳細(xì)については、PHP 中國(guó)語(yǔ) Web サイトの他の関連記事を參照してください。