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 特征现在有一个

PHPDoc 和 @template 标签，这是保留的泛型标签之一。正如您可能已经猜到的，框架的许多部分都使用了泛型。

/**
 * @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 和@使用。

泛型类型的规则是使用

类型参数定义的。在PHPDocs中，我们使用@template标签对它们进行注释。类型参数名称可以是任何名称，只要不使用现有的类名称即可。您还可以使用 of 关键字限制可以使用哪些类型来代替带有上限的类型参数。这称为有界类型参数。

<?php namespace Illuminate\Database\Eloquent;

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

PHP 泛型的类型

通用函数

泛型函数与普通函数完全相同，但是它具有类型参数。这允许以更通用的方式使用通用方法。

以 IlluminateSupportValidatedInput::enum 方法为例：

• 它定义了一个类型参数 TEnum。

• $enumClass 参数是伪类型 class-string，并且绑定到相同类型参数 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 方法的返回类型。

另一个例子是，如果我们有一个订单模型，它有一个本地范围来根据订单状态过滤订单。范围方法应指定 TModel 类型

parameters:
    ignoreErrors:
        -
            identifier: missingType.generics

ℹ️ info：命名空间 IlluminateDatabaseEloquentRelations 中的所有 Eloquent 关系类（例如 BelongsTo 和 HasOne）现在都是通用的。

通用接口

通用接口并没有那么不同。 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();
}

该接口定义了两个类型参数：array-key类型的TKey（可以是int或string）和TValue。这两个参数用于定义 toArray 函数的返回类型。这是一个例子：

<?php namespace Illuminate\Database\Eloquent;

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

用户类实现 Arrayable 接口，并指定 Tkey 类型为 int，TValue 类型为 string。

通用特征

我们在本文开头的错误中遇到了 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));
}
</tenum>

HasFactory 定义了一个类型参数 TFactory，它绑定到 IlluminateDatabaseEloquentFactoriesFactory 的子类。那么如何修复这个错误呢？

使用 Trait 时必须指定 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中文网其他相关文章！