如果您是Laravel 的Web 應(yīng)用程式建構(gòu)者，並且碰巧使用PHPStan 進(jìn)行靜態(tài)程式碼分析，那麼當(dāng)您升級(jí)到Laravel 11.x.

使用

PHPStan 全新安裝 Laravel 時(shí)，第一次執(zhí)行 ./vendor/bin/phpstan 時(shí)會(huì)拋出以下錯(cuò)誤：

 ------ -----------------------------------------------------------------------------------
  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 特徵現(xiàn)在有一個(gè)

PHPDoc 和 @template 標(biāo)籤，這是保留的泛型標(biāo)籤之一。正如您可能已經(jīng)猜到的，框架的許多部分都使用了泛型。

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

雖然不建議這樣做，但只需將這些程式碼行新增到您的 phpstan.neon 檔案即可忽略此類錯(cuò)誤：

parameters:
    ignoreErrors:
        -
            identifier: missingType.generics

但是，泛型並不難理解，所以讓我們開(kāi)始吧！

什麼是泛型？

程式設(shè)計(jì)中的泛型是指允許您編寫可處理多種資料類型的程式碼的功能。您無(wú)需為每種資料類型編寫單獨(dú)的程式碼，而是可以編寫一段通用的程式碼，該程式碼可以在保持類型安全的同時(shí)對(duì)各種類型進(jìn)行操作，這與使用混合或物件等通用類型不同。

採(cǎi)用

Laravel 10 中的 IlluminateDatabaseConcernsBuildsQueries::first 方法，它可以傳回 Model 的實(shí)例、通用物件、像 IlluminateDatabaseEloquentBuilder 一樣使用它的類別的實(shí)例或 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();
}

泛型語(yǔ)法

PHP 中不支援泛型作為一等公民，為了擁有它們，我們使用

PHPDocs 標(biāo)籤 @template、@template-covariant、@template-contravariant、@extends、@implements 和@使用。

泛型類型的規(guī)則是使用

型別參數(shù)定義的。 在PHPDocs中，我們使用@template標(biāo)籤對(duì)它們進(jìn)行註釋。類型參數(shù)名稱可以是任何名稱，只要不使用現(xiàn)有的類別名稱即可。您也可以使用 of 關(guān)鍵字限制可以使用哪些類型來(lái)取代帶有上限的類型參數(shù)。這稱為有界型參數(shù)。

<?php

namespace Illuminate\Database\Eloquent;

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

PHP 泛型的類型

通用函數(shù)

泛型函數(shù)與普通函數(shù)完全相同，但是它具有型別參數(shù)。這允許以更通用的方式使用通用方法。

以 IlluminateSupportValidatedInput::enum 方法為例：

• 它定義了一個(gè)型別參數(shù) TEnum。

• $enumClass 參數(shù)是偽型別 class-string，並且綁定到相同型別參數(shù) 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！

通用類別

泛型類別允許建立可以對(duì)任何資料類型進(jìn)行操作的類，同時(shí)確保類型安全。它們?cè)试S使用特定類型的佔(zhàn)位符來(lái)定義類，稍後可以在類實(shí)例化時(shí)替換該佔(zhàn)位符。

Laravel 原始碼中的一個(gè)很好的例子是 IlluminateDatabaseEloquentBuilder 類別：

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

類型參數(shù) TModel 被定義並綁定到 IlluminateDatabaseEloquentModel 的任何子類別。相同的型別參數(shù)用作 make 方法的傳回類型。

另一個(gè)例子是，如果我們有一個(gè)訂單模型，它有一個(gè)本地範(fàn)圍來(lái)根據(jù)訂單狀態(tài)過(guò)濾訂單。範(fàn)圍方法應(yīng)指定 TModel 類型

parameters:
    ignoreErrors:
        -
            identifier: missingType.generics

?? info：命名空間 IlluminateDatabaseEloquentRelations 中的所有 Eloquent 關(guān)係類別（例如 BelongsTo 和 HasOne）現(xiàn)在都是通用的。

通用介面

通用介面並沒(méi)有那麼不同。 IlluminateContractsSupportArrayable 是通用介面的範(fàn)例

/**
 * 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è)型別參數(shù)：array-key類型的TKey（可以是int或string）和TValue。這兩個(gè)參數(shù)用於定義 toArray 函數(shù)的傳回類型。這是一個(gè)例子：

<?php

namespace Illuminate\Database\Eloquent;

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

使用者類別實(shí)作 Arrayable 接口，並指定 Tkey 類型為 int，TValue 型為 string。

通用特徵

我們?cè)诒疚拈_(kāi)頭的錯(cuò)誤中遇到了 IlluminateDatabaseEloquentFactoriesHasFactory 特徵。讓我們仔細(xì)看看：

/**
 * @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 定義了一個(gè)型別參數(shù) TFactory，它綁定到 IlluminateDatabaseEloquentFactoriesFactory 的子類別。那麼要如何修復(fù)這個(gè)錯(cuò)誤呢？

使用 Trait 時(shí)必須指定 TFactory 類型。因此，HasFactory 特徵的 use 語(yǔ)句需要使用 PHPDocs @use:
進(jìn)行註釋

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

保持通用性

擴(kuò)充類別、實(shí)作介面或使用特徵時(shí)，可以保持子類別中的通用性。

透過(guò)在子類別上方定義相同的類型參數(shù)並將其傳遞給 @extends、@implements 和 @use 標(biāo)籤來(lái)實(shí)現(xiàn)保留通用性。

我們將使用 IlluminateDatabaseConcernsBuildsQueries 通用特徵作為範(fàn)例，

它定義了一個(gè)型別參數(shù)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 類別使用此特徵，但透過(guò)向其傳遞 TModel 參數(shù)類型來(lái)保持其通用性?，F(xiàn)在由客戶端程式碼來(lái)指定 TModel 的類型，從而在 BuildsQueries 特徵中指定 TValue。

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

最後的想法

總之，雖然 PHP 並不像其他程式語(yǔ)言那樣原生支援泛型，但引入高階類型提示和工具（例如 PHPStan）允許開(kāi)發(fā)人員在程式碼中實(shí)現(xiàn)類似泛型的功能。透過(guò)利用 PHPDocs、參數(shù)化類別和接口，您可以創(chuàng)建更靈活和類型安全的應(yīng)用程序，從而提高程式碼的可重用性和可維護(hù)性。隨著 PHP 的不斷發(fā)展，社群對(duì)類型安全和靜態(tài)分析的日益關(guān)注可能會(huì)帶來(lái)更強(qiáng)大的泛型實(shí)現(xiàn)解決方案。接受這些實(shí)踐不僅可以提高您的編碼技能，還有助於開(kāi)發(fā)經(jīng)得起時(shí)間考驗(yàn)的高品質(zhì)軟體。

以上是Laravel 11 中的 PHP 泛型的詳細(xì)內(nèi)容。更多資訊請(qǐng)關(guān)注PHP中文網(wǎng)其他相關(guān)文章！