Eloquent: 入门

介绍
生成模型类
Eloquent 模型约定
检索模型
检索单个模型/聚合
- 检索或创建模型
- 检索聚合
插入和更新模型
删除模型
- 软删除
- 查询软删除模型
修剪模型
复制模型
查询范围
比较模型
事件

介绍

Laravel 包含 Eloquent，一个对象关系映射器 (ORM)，使与数据库的交互变得愉快。使用 Eloquent 时，每个数据库表都有一个对应的“模型”用于与该表交互。除了从数据库表中检索记录外，Eloquent 模型还允许您插入、更新和删除表中的记录。

NOTE

在开始之前，请确保在应用程序的 config/database.php 配置文件中配置数据库连接。有关配置数据库的更多信息，请查看数据库配置文档。

生成模型类

首先，让我们创建一个 Eloquent 模型。模型通常位于 app\Models 目录中，并扩展 Illuminate\Database\Eloquent\Model 类。您可以使用 make:model Artisan 命令生成一个新模型：

shell

php artisan make:model Flight

如果您希望在生成模型时生成一个数据库迁移，可以使用 --migration 或 -m 选项：

shell

php artisan make:model Flight --migration

生成模型时，您可以生成各种其他类型的类，例如工厂、填充器、策略、控制器和表单请求。此外，这些选项可以组合在一起以一次创建多个类：

shell

# 生成一个模型和一个 FlightFactory 类...
php artisan make:model Flight --factory
php artisan make:model Flight -f

# 生成一个模型和一个 FlightSeeder 类...
php artisan make:model Flight --seed
php artisan make:model Flight -s

# 生成一个模型和一个 FlightController 类...
php artisan make:model Flight --controller
php artisan make:model Flight -c

# 生成一个模型、FlightController 资源类和表单请求类...
php artisan make:model Flight --controller --resource --requests
php artisan make:model Flight -crR

# 生成一个模型和一个 FlightPolicy 类...
php artisan make:model Flight --policy

# 生成一个模型和迁移、工厂、填充器和控制器...
php artisan make:model Flight -mfsc

# 快捷方式生成一个模型、迁移、工厂、填充器、策略、控制器和表单请求...
php artisan make:model Flight --all
php artisan make:model Flight -a

# 生成一个枢纽模型...
php artisan make:model Member --pivot
php artisan make:model Member -p

检查模型

有时，仅通过浏览代码可能很难确定模型的所有可用属性和关系。相反，尝试使用 model:show Artisan 命令，它提供了模型的所有属性和关系的便捷概述：

shell

php artisan model:show Flight

Eloquent 模型约定

通过 make:model 命令生成的模型将放置在 app/Models 目录中。让我们检查一个基本的模型类并讨论一些 Eloquent 的关键约定：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    // ...
}

表名

在浏览上面的示例后，您可能已经注意到我们没有告诉 Eloquent 哪个数据库表对应于我们的 Flight 模型。按照惯例，类的“蛇形命名法”复数名称将用作表名，除非明确指定了其他名称。因此，在这种情况下，Eloquent 将假定 Flight 模型存储在 flights 表中，而 AirTrafficController 模型将存储在 air_traffic_controllers 表中。

如果您的模型对应的数据库表不符合此约定，您可以通过在模型上定义一个 table 属性来手动指定模型的表名：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * 与模型关联的表。
     *
     * @var string
     */
    protected $table = 'my_flights';
}

主键

Eloquent 还假定每个模型对应的数据库表都有一个名为 id 的主键列。如果需要，您可以在模型上定义一个受保护的 $primaryKey 属性，以指定一个不同的列作为模型的主键：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * 与表关联的主键。
     *
     * @var string
     */
    protected $primaryKey = 'flight_id';
}

此外，Eloquent 假定主键是一个递增的整数值，这意味着 Eloquent 将自动将主键转换为整数。如果您希望使用非递增或非数字主键，您必须在模型上定义一个公共的 $incrementing 属性，并将其设置为 false：

php

<?php

class Flight extends Model
{
    /**
     * 指示模型的 ID 是否是自动递增的。
     *
     * @var bool
     */
    public $incrementing = false;
}

如果模型的主键不是整数，您应该在模型上定义一个受保护的 $keyType 属性。此属性的值应为 string：

php

<?php

class Flight extends Model
{
    /**
     * 主键 ID 的数据类型。
     *
     * @var string
     */
    protected $keyType = 'string';
}

“复合”主键

Eloquent 要求每个模型至少有一个唯一标识的“ID”可以作为其主键。Eloquent 模型不支持“复合”主键。但是，您可以自由地在数据库表中添加额外的多列唯一索引，除了表的唯一标识主键之外。

UUID 和 ULID 键

除了使用递增的整数作为 Eloquent 模型的主键外，您还可以选择使用 UUID。UUID 是 36 个字符长的全局唯一字母数字标识符。

如果您希望模型使用 UUID 键而不是递增的整数键，可以在模型上使用 Illuminate\Database\Eloquent\Concerns\HasUuids trait。当然，您应该确保模型具有 UUID 等效主键列：

php

use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    use HasUuids;

    // ...
}

$article = Article::create(['title' => 'Traveling to Europe']);

$article->id; // "8f8e8478-9035-4d23-b9a7-62f4d2612ce5"

默认情况下，HasUuids trait 将为您的模型生成“有序” UUID。这些 UUID 对于索引数据库存储更为高效，因为它们可以按字典顺序排序。

您可以通过在模型上定义一个 newUniqueId 方法来覆盖给定模型的 UUID 生成过程。此外，您可以通过在模型上定义一个 uniqueIds 方法来指定哪些列应该接收 UUID：

php

use Ramsey\Uuid\Uuid;

/**
 * 为模型生成一个新的 UUID。
 */
public function newUniqueId(): string
{
    return (string) Uuid::uuid4();
}

/**
 * 获取应接收唯一标识符的列。
 *
 * @return array<int, string>
 */
public function uniqueIds(): array
{
    return ['id', 'discount_code'];
}

如果您愿意，您可以选择使用“ULIDs”而不是 UUID。ULIDs 类似于 UUID；然而，它们只有 26 个字符长。像有序 UUID 一样，ULIDs 可以按字典顺序排序以实现高效的数据库索引。要使用 ULIDs，您应该在模型上使用 Illuminate\Database\Eloquent\Concerns\HasUlids trait。您还应该确保模型具有 ULID 等效主键列：

php

use Illuminate\Database\Eloquent\Concerns\HasUlids;
use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    use HasUlids;

    // ...
}

$article = Article::create(['title' => 'Traveling to Asia']);

$article->id; // "01gd4d3tgrrfqeda94gdbtdk5c"

时间戳

默认情况下，Eloquent 期望模型对应的数据库表中存在 created_at 和 updated_at 列。Eloquent 会在创建或更新模型时自动设置这些列的值。如果您不希望这些列由 Eloquent 自动管理，您应该在模型上定义一个 $timestamps 属性，并将其值设置为 false：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * 指示模型是否应被时间戳。
     *
     * @var bool
     */
    public $timestamps = false;
}

如果您需要自定义模型时间戳的格式，请在模型上设置 $dateFormat 属性。此属性确定日期属性在数据库中的存储方式以及模型序列化为数组或 JSON 时的格式：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * 模型日期列的存储格式。
     *
     * @var string
     */
    protected $dateFormat = 'U';
}

如果您需要自定义用于存储时间戳的列的名称，可以在模型上定义 CREATED_AT 和 UPDATED_AT 常量：

php

<?php

class Flight extends Model
{
    const CREATED_AT = 'creation_date';
    const UPDATED_AT = 'updated_date';
}

如果您希望在不修改模型的 updated_at 时间戳的情况下执行模型操作，可以在传递给 withoutTimestamps 方法的闭包中操作模型：

php

Model::withoutTimestamps(fn () => $post->increment('reads'));

数据库连接

默认情况下，所有 Eloquent 模型将使用为应用程序配置的默认数据库连接。如果您希望指定在与特定模型交互时应使用的不同连接，您应该在模型上定义一个 $connection 属性：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * 模型应使用的数据库连接。
     *
     * @var string
     */
    protected $connection = 'mysql';
}

默认属性值

默认情况下，新实例化的模型实例不会包含任何属性值。如果您希望为模型的某些属性定义默认值，可以在模型上定义一个 $attributes 属性。放置在 $attributes 数组中的属性值应为其原始的“可存储”格式，就像它们刚从数据库中读取一样：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * 模型的默认属性值。
     *
     * @var array
     */
    protected $attributes = [
        'options' => '[]',
        'delayed' => false,
    ];
}

配置 Eloquent 严格性

Laravel 提供了几种方法，允许您在各种情况下配置 Eloquent 的行为和“严格性”。

首先，preventLazyLoading 方法接受一个可选的布尔参数，指示是否应防止惰性加载。例如，您可能希望仅在非生产环境中禁用惰性加载，以便即使在生产代码中意外存在惰性加载关系，生产环境也能正常运行。通常，此方法应在应用程序的 AppServiceProvider 的 boot 方法中调用：

php

use Illuminate\Database\Eloquent\Model;

/**
 * 启动任何应用程序服务。
 */
public function boot(): void
{
    Model::preventLazyLoading(! $this->app->isProduction());
}

此外，您可以通过调用 preventSilentlyDiscardingAttributes 方法来指示 Laravel 在尝试填充不可填充的属性时抛出异常。这可以帮助防止在本地开发期间尝试设置尚未添加到模型的 fillable 数组中的属性时出现意外错误：

php

Model::preventSilentlyDiscardingAttributes(! $this->app->isProduction());

检索模型

一旦您创建了模型和其关联的数据库表，您就可以开始从数据库中检索数据。您可以将每个 Eloquent 模型视为一个强大的查询构建器，允许您流畅地查询与模型关联的数据库表。模型的 all 方法将检索模型关联的数据库表中的所有记录：

php

use App\Models\Flight;

foreach (Flight::all() as $flight) {
    echo $flight->name;
}

构建查询

Eloquent 的 all 方法将返回模型表中的所有结果。然而，由于每个 Eloquent 模型都充当查询构建器，您可以向查询添加额外的约束，然后调用 get 方法以检索结果：

php

$flights = Flight::where('active', 1)
    ->orderBy('name')
    ->take(10)
    ->get();

NOTE

由于 Eloquent 模型是查询构建器，您应该查看 Laravel 的查询构建器提供的所有方法。您可以在编写 Eloquent 查询时使用这些方法中的任何一个。

刷新模型

如果您已经有一个从数据库中检索到的 Eloquent 模型实例，您可以使用 fresh 和 refresh 方法“刷新”模型。fresh 方法将重新从数据库中检索模型。现有的模型实例不会受到影响：

php

$flight = Flight::where('number', 'FR 900')->first();

$freshFlight = $flight->fresh();

refresh 方法将使用来自数据库的新数据重新填充现有模型。此外，所有已加载的关系也将被刷新：

php

$flight = Flight::where('number', 'FR 900')->first();

$flight->number = 'FR 456';

$flight->refresh();

$flight->number; // "FR 900"

集合

正如我们所见，Eloquent 方法如 all 和 get 从数据库中检索多个记录。然而，这些方法不会返回一个普通的 PHP 数组。相反，返回的是 Illuminate\Database\Eloquent\Collection 的一个实例。

Eloquent Collection 类扩展了 Laravel 的基础 Illuminate\Support\Collection 类，该类提供了多种有用的方法用于与数据集合交互。例如，reject 方法可用于根据调用的闭包的结果从集合中移除模型：

php

$flights = Flight::where('destination', 'Paris')->get();

$flights = $flights->reject(function (Flight $flight) {
    return $flight->cancelled;
});

除了 Laravel 的基础集合类提供的方法外，Eloquent 集合类还提供了一些专门用于与 Eloquent 模型集合交互的额外方法。

由于 Laravel 的所有集合都实现了 PHP 的可迭代接口，您可以像数组一样遍历集合：

php

foreach ($flights as $flight) {
    echo $flight->name;
}

分块结果

如果您尝试通过 all 或 get 方法加载成千上万的 Eloquent 记录，您的应用程序可能会耗尽内存。与其使用这些方法，不如使用 chunk 方法更有效地处理大量模型。

chunk 方法将检索一部分 Eloquent 模型，并将它们传递给一个闭包进行处理。由于每次只检索当前块的 Eloquent 模型，因此 chunk 方法在处理大量模型时将显著减少内存使用：

php

use App\Models\Flight;
use Illuminate\Database\Eloquent\Collection;

Flight::chunk(200, function (Collection $flights) {
    foreach ($flights as $flight) {
        // ...
    }
});

传递给 chunk 方法的第一个参数是您希望每个“块”接收的记录数。作为第二个参数传递的闭包将在从数据库中检索到的每个块上调用。将执行一个数据库查询以检索传递给闭包的每个块的记录。

如果您根据将在迭代结果时更新的列过滤 chunk 方法的结果，您应该使用 chunkById 方法。在这些场景中使用 chunk 方法可能会导致意外和不一致的结果。在内部，chunkById 方法将始终检索 id 列大于上一个块中最后一个模型的模型：

php

Flight::where('departed', true)
    ->chunkById(200, function (Collection $flights) {
        $flights->each->update(['departed' => false]);
    }, column: 'id');

由于 chunkById 和 lazyById 方法向正在执行的查询添加了自己的“where”条件，您通常应该在闭包中逻辑分组自己的条件：

php

Flight::where(function ($query) {
    $query->where('delayed', true)->orWhere('cancelled', true);
})->chunkById(200, function (Collection $flights) {
    $flights->each->update([
        'departed' => false,
        'cancelled' => true
    ]);
}, column: 'id');

使用惰性集合分块

lazy 方法在后台执行查询时类似于chunk 方法，但不是将每个块直接传递给回调，而是返回一个扁平化的LazyCollection Eloquent 模型，让您可以将结果视为单个流进行交互：

php

use App\Models\Flight;

foreach (Flight::lazy() as $flight) {
    // ...
}

如果您根据将在迭代结果时更新的列过滤 lazy 方法的结果，您应该使用 lazyById 方法。在内部，lazyById 方法将始终检索 id 列大于上一个块中最后一个模型的模型：

php

Flight::where('departed', true)
    ->lazyById(200, column: 'id')
    ->each->update(['departed' => false]);

您可以使用 lazyByIdDesc 方法根据 id 的降序过滤结果。

游标

与 lazy 方法类似，cursor 方法可用于在迭代成千上万的 Eloquent 模型记录时显著减少应用程序的内存消耗。

cursor 方法将只执行一个数据库查询；然而，单个 Eloquent 模型在实际迭代之前不会被填充。因此，在迭代游标时，内存中只保留一个 Eloquent 模型。

WARNING

由于 cursor 方法在任何时候只在内存中保留一个 Eloquent 模型，因此无法急切加载关系。如果您需要急切加载关系，请考虑使用lazy 方法。

在内部，cursor 方法使用 PHP 生成器来实现此功能：

php

use App\Models\Flight;

foreach (Flight::where('destination', 'Zurich')->cursor() as $flight) {
    // ...
}

cursor 返回一个 Illuminate\Support\LazyCollection 实例。惰性集合允许您在一次只加载一个模型到内存中时使用许多典型 Laravel 集合可用的方法：

php

use App\Models\User;

$users = User::cursor()->filter(function (User $user) {
    return $user->id > 500;
});

foreach ($users as $user) {
    echo $user->id;
}

尽管 cursor 方法使用的内存比常规查询少得多（因为一次只在内存中保留一个 Eloquent 模型），但它最终仍会耗尽内存。这是因为PHP 的 PDO 驱动程序在其缓冲区中内部缓存所有原始查询结果。如果您正在处理大量 Eloquent 记录，请考虑使用lazy 方法。

高级子查询

子查询选择

Eloquent 还提供高级子查询支持，允许您在单个查询中从相关表中提取信息。例如，假设我们有一个航班 destinations 表和一个 flights 表。flights 表包含一个 arrived_at 列，指示航班到达目的地的时间。

使用查询构建器的 select 和 addSelect 方法提供的子查询功能，我们可以使用单个查询选择所有 destinations 和最近到达该目的地的航班的名称：

php

use App\Models\Destination;
use App\Models\Flight;

return Destination::addSelect(['last_flight' => Flight::select('name')
    ->whereColumn('destination_id', 'destinations.id')
    ->orderByDesc('arrived_at')
    ->limit(1)
])->get();

子查询排序

此外，查询构建器的 orderBy 函数支持子查询。继续使用我们的航班示例，我们可以使用此功能根据最后一次航班到达目的地的时间对所有目的地进行排序。同样，这可以在执行单个数据库查询时完成：

php

return Destination::orderByDesc(
    Flight::select('arrived_at')
        ->whereColumn('destination_id', 'destinations.id')
        ->orderByDesc('arrived_at')
        ->limit(1)
)->get();

检索单个模型/聚合

除了检索与给定查询匹配的所有记录外，您还可以使用 find、first 或 firstWhere 方法检索单个记录。这些方法返回一个单一的模型实例，而不是返回一个模型集合：

php

use App\Models\Flight;

// 通过主键检索模型...
$flight = Flight::find(1);

// 检索与查询约束匹配的第一个模型...
$flight = Flight::where('active', 1)->first();

// 检索与查询约束匹配的第一个模型的替代方法...
$flight = Flight::firstWhere('active', 1);

有时您可能希望在没有找到结果时执行其他操作。findOr 和 firstOr 方法将返回一个单一的模型实例，或者如果没有找到结果，则执行给定的闭包。闭包返回的值将被视为方法的结果：

php

$flight = Flight::findOr(1, function () {
    // ...
});

$flight = Flight::where('legs', '>', 3)->firstOr(function () {
    // ...
});

未找到异常

有时您可能希望在未找到模型时抛出异常。这在路由或控制器中特别有用。findOrFail 和 firstOrFail 方法将检索查询的第一个结果；然而，如果没有找到结果，将抛出一个 Illuminate\Database\Eloquent\ModelNotFoundException：

php

$flight = Flight::findOrFail(1);

$flight = Flight::where('legs', '>', 3)->firstOrFail();

如果 ModelNotFoundException 未被捕获，将自动向客户端发送 404 HTTP 响应：

php

use App\Models\Flight;

Route::get('/api/flights/{id}', function (string $id) {
    return Flight::findOrFail($id);
});

检索或创建模型

firstOrCreate 方法将尝试使用给定的列/值对定位数据库记录。如果在数据库中找不到模型，将使用第一个数组参数与可选的第二个数组参数合并的属性插入一条记录：

firstOrNew 方法类似于 firstOrCreate，将尝试在数据库中定位与给定属性匹配的记录。然而，如果未找到模型，将返回一个新的模型实例。请注意，firstOrNew 返回的模型尚未持久化到数据库。您需要手动调用 save 方法以将其持久化：

php

use App\Models\Flight;

// 通过名称检索航班或在不存在时创建它...
$flight = Flight::firstOrCreate([
    'name' => 'London to Paris'
]);

// 通过名称检索航班或使用名称、延迟和到达时间属性创建它...
$flight = Flight::firstOrCreate(
    ['name' => 'London to Paris'],
    ['delayed' => 1, 'arrival_time' => '11:30']
);

// 通过名称检索航班或实例化一个新的 Flight 实例...
$flight = Flight::firstOrNew([
    'name' => 'London to Paris'
]);

// 通过名称检索航班或实例化具有名称、延迟和到达时间属性的航班...
$flight = Flight::firstOrNew(
    ['name' => 'Tokyo to Sydney'],
    ['delayed' => 1, 'arrival_time' => '11:30']
);

检索聚合

在与 Eloquent 模型交互时，您还可以使用 Laravel 查询构建器提供的 count、sum、max 和其他聚合方法。正如您所期望的，这些方法返回一个标量值，而不是 Eloquent 模型实例：

php

$count = Flight::where('active', 1)->count();

$max = Flight::where('active', 1)->max('price');

插入和更新模型

插入

当然，使用 Eloquent 时，我们不仅需要从数据库中检索模型。我们还需要插入新记录。幸运的是，Eloquent 使这变得简单。要将新记录插入数据库，您应该实例化一个新的模型实例并在模型上设置属性。然后，在模型实例上调用 save 方法：

php

<?php

namespace App\Http\Controllers;

use App\Models\Flight;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class FlightController extends Controller
{
    /**
     * 在数据库中存储一个新的航班。
     */
    public function store(Request $request): RedirectResponse
    {
        // 验证请求...

        $flight = new Flight;

        $flight->name = $request->name;

        $flight->save();

        return redirect('/flights');
    }
}

在此示例中，我们将传入的 HTTP 请求中的 name 字段分配给 App\Models\Flight 模型实例的 name 属性。当我们调用 save 方法时，将在数据库中插入一条记录。模型的 created_at 和 updated_at 时间戳将在调用 save 方法时自动设置，因此无需手动设置它们。

或者，您可以使用 create 方法通过单个 PHP 语句“保存”一个新模型。插入的模型实例将由 create 方法返回给您：

php

use App\Models\Flight;

$flight = Flight::create([
    'name' => 'London to Paris',
]);

然而，在使用 create 方法之前，您需要在模型类上指定一个 fillable 或 guarded 属性。这些属性是必需的，因为所有 Eloquent 模型默认情况下都受到批量赋值漏洞的保护。要了解有关批量赋值的更多信息，请查阅批量赋值文档。

更新

save 方法也可用于更新已存在于数据库中的模型。要更新模型，您应该检索它并设置您希望更新的任何属性。然后，您应该调用模型的 save 方法。同样，updated_at 时间戳将自动更新，因此无需手动设置其值：

php

use App\Models\Flight;

$flight = Flight::find(1);

$flight->name = 'Paris to London';

$flight->save();

有时，您可能需要更新现有模型或在没有匹配模型时创建一个新模型。与 firstOrCreate 方法类似，updateOrCreate 方法会持久化模型，因此无需手动调用 save 方法。

在下面的示例中，如果存在一个 departure 位置为 Oakland 且 destination 位置为 San Diego 的航班，其 price 和 discounted 列将被更新。如果不存在这样的航班，将创建一个新航班，其属性是第一个参数数组与第二个参数数组合并的结果：

php

$flight = Flight::updateOrCreate(
    ['departure' => 'Oakland', 'destination' => 'San Diego'],
    ['price' => 99, 'discounted' => 1]
);

批量更新

更新也可以针对与给定查询匹配的模型执行。在此示例中，所有 active 且 destination 为 San Diego 的航班将被标记为延迟：

php

Flight::where('active', 1)
    ->where('destination', 'San Diego')
    ->update(['delayed' => 1]);

update 方法期望一个表示应更新的列的列和值对的数组。update 方法返回受影响的行数。

WARNING

在通过 Eloquent 发出批量更新时，不会为更新的模型触发 saving、saved、updating 和 updated 模型事件。这是因为在发出批量更新时，模型从未实际检索到。

检查属性更改

Eloquent 提供了 isDirty、isClean 和 wasChanged 方法来检查模型的内部状态，并确定其属性自模型最初检索以来如何发生了变化。

isDirty 方法确定自模型检索以来模型的任何属性是否已更改。您可以将特定属性名称或属性数组传递给 isDirty 方法，以确定任何属性是否“脏”。isClean 方法将确定自模型检索以来属性是否保持不变。此方法还接受一个可选的属性参数：

php

use App\Models\User;

$user = User::create([
    'first_name' => 'Taylor',
    'last_name' => 'Otwell',
    'title' => 'Developer',
]);

$user->title = 'Painter';

$user->isDirty(); // true
$user->isDirty('title'); // true
$user->isDirty('first_name'); // false
$user->isDirty(['first_name', 'title']); // true

$user->isClean(); // false
$user->isClean('title'); // false
$user->isClean('first_name'); // true
$user->isClean(['first_name', 'title']); // false

$user->save();

$user->isDirty(); // false
$user->isClean(); // true

wasChanged 方法确定在当前请求周期内最后一次保存模型时是否更改了任何属性。如果需要，您可以传递一个属性名称以查看特定属性是否已更改：

php

$user = User::create([
    'first_name' => 'Taylor',
    'last_name' => 'Otwell',
    'title' => 'Developer',
]);

$user->title = 'Painter';

$user->save();

$user->wasChanged(); // true
$user->wasChanged('title'); // true
$user->wasChanged(['title', 'slug']); // true
$user->wasChanged('first_name'); // false
$user->wasChanged(['first_name', 'title']); // true

getOriginal 方法返回一个包含模型原始属性的数组，无论自检索模型以来对模型进行了哪些更改。如果需要，您可以传递一个特定的属性名称以获取特定属性的原始值：

php

$user = User::find(1);

$user->name; // John
$user->email; // john@example.com

$user->name = 'Jack';
$user->name; // Jack

$user->getOriginal('name'); // John
$user->getOriginal(); // 原始属性的数组...

getChanges 方法返回一个包含模型最后一次保存时更改的属性的数组：

php

$user = User::find(1);

$user->name; // John
$user->email; // john@example.com

$user->update([
    'name' => 'Jack',
    'email' => 'jack@example.com',
]);

$user->getChanges();

/*
    [
        'name' => 'Jack',
        'email' => 'jack@example.com',
    ]
*/

批量赋值

您可以使用 create 方法通过单个 PHP 语句“保存”一个新模型。插入的模型实例将由该方法返回给您：

php

use App\Models\Flight;

$flight = Flight::create([
    'name' => 'London to Paris',
]);

然而，在使用 create 方法之前，您需要在模型类上指定一个 fillable 或 guarded 属性。这些属性是必需的，因为所有 Eloquent 模型默认情况下都受到批量赋值漏洞的保护。

批量赋值漏洞发生在用户传递了一个意外的 HTTP 请求字段，并且该字段更改了数据库中您未预期的列。例如，恶意用户可能通过 HTTP 请求发送一个 is_admin 参数，然后将其传递给模型的 create 方法，从而允许用户将自己提升为管理员。

因此，首先，您应该定义要批量赋值的模型属性。您可以使用模型上的 $fillable 属性来执行此操作。例如，让我们将 Flight 模型的 name 属性设为可批量赋值：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Flight extends Model
{
    /**
     * 可批量赋值的属性。
     *
     * @var array<int, string>
     */
    protected $fillable = ['name'];
}

一旦您指定了哪些属性是可批量赋值的，您就可以使用 create 方法在数据库中插入一条新记录。create 方法返回新创建的模型实例：

php

$flight = Flight::create(['name' => 'London to Paris']);

如果您已经有一个模型实例，您可以使用 fill 方法用属性数组填充它：

php

$flight->fill(['name' => 'Amsterdam to Frankfurt']);

批量赋值和 JSON 列

在分配 JSON 列时，必须在模型的 $fillable 数组中指定每个列的可批量赋值键。出于安全原因，Laravel 不支持在使用 guarded 属性时更新嵌套的 JSON 属性：

php

/**
 * 可批量赋值的属性。
 *
 * @var array<int, string>
 */
protected $fillable = [
    'options->enabled',
];

允许批量赋值

如果您希望使所有属性都可批量赋值，可以将模型的 $guarded 属性定义为空数组。如果您选择取消保护模型，您应该特别注意始终手工制作传递给 Eloquent 的 fill、create 和 update 方法的数组：

php

/**
 * 不可批量赋值的属性。
 *
 * @var array<string>|bool
 */
protected $guarded = [];

批量赋值异常

默认情况下，在执行批量赋值操作时，不包含在 $fillable 数组中的属性会被静默丢弃。在生产环境中，这是预期的行为；然而，在本地开发期间，这可能会导致混淆，为什么模型更改没有生效。

如果您愿意，您可以通过调用 preventSilentlyDiscardingAttributes 方法来指示 Laravel 在尝试填充不可填充的属性时抛出异常。通常，此方法应在应用程序的 AppServiceProvider 类的 boot 方法中调用：

php

use Illuminate\Database\Eloquent\Model;

/**
 * 启动任何应用程序服务。
 */
public function boot(): void
{
    Model::preventSilentlyDiscardingAttributes($this->app->isLocal());
}

Upserts

Eloquent 的 upsert 方法可用于在单个原子操作中更新或创建记录。该方法的第一个参数由要插入或更新的值组成，而第二个参数列出了在关联表中唯一标识记录的列。该方法的第三个也是最后一个参数是一个数组，列出了如果数据库中已存在匹配记录时应更新的列。如果在模型上启用了时间戳，upsert 方法将自动设置 created_at 和 updated_at 时间戳：

php

Flight::upsert([
    ['departure' => 'Oakland', 'destination' => 'San Diego', 'price' => 99],
    ['departure' => 'Chicago', 'destination' => 'New York', 'price' => 150]
], uniqueBy: ['departure', 'destination'], update: ['price']);

WARNING

除了 SQL Server 之外的所有数据库都要求 upsert 方法的第二个参数中的列具有“主”或“唯一”索引。此外，MariaDB 和 MySQL 数据库驱动程序会忽略 upsert 方法的第二个参数，并始终使用表的“主”和“唯一”索引来检测现有记录。

删除模型

要删除模型，您可以在模型实例上调用 delete 方法：

php

use App\Models\Flight;

$flight = Flight::find(1);

$flight->delete();

通过主键删除现有模型

在上面的示例中，我们在调用 delete 方法之前从数据库中检索模型。然而，如果您知道模型的主键，您可以通过调用 destroy 方法在不显式检索模型的情况下删除模型。除了接受单个主键外，destroy 方法还接受多个主键、主键数组或主键的集合：

php

Flight::destroy(1);

Flight::destroy(1, 2, 3);

Flight::destroy([1, 2, 3]);

Flight::destroy(collect([1, 2, 3]));

如果您正在使用软删除模型，您可以通过 forceDestroy 方法永久删除模型：

php

Flight::forceDestroy(1);

WARNING

destroy 方法会单独加载每个模型并调用 delete 方法，以便为每个模型正确分派 deleting 和 deleted 事件。

使用查询删除模型

当然，您可以构建一个 Eloquent 查询来删除所有符合查询条件的模型。在这个例子中，我们将删除所有标记为不活跃的航班。与批量更新类似，批量删除不会为被删除的模型调度模型事件：

php

$deleted = Flight::where('active', 0)->delete();

要删除表中的所有模型，您应该执行一个不添加任何条件的查询：

php

$deleted = Flight::query()->delete();

WARNING

当通过 Eloquent 执行批量删除语句时，deleting 和 deleted 模型事件将不会为被删除的模型调度。这是因为在执行删除语句时，模型实际上从未被检索。

软删除

除了实际从数据库中删除记录外，Eloquent 还可以“软删除”模型。当模型被软删除时，它们实际上并没有从数据库中删除。相反，模型上会设置一个 deleted_at 属性，指示模型被“删除”的日期和时间。要为模型启用软删除，请将 Illuminate\Database\Eloquent\SoftDeletes trait 添加到模型中：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;

class Flight extends Model
{
    use SoftDeletes;
}

NOTE

SoftDeletes trait 会自动将 deleted_at 属性转换为 DateTime / Carbon 实例。

您还应该将 deleted_at 列添加到数据库表中。Laravel schema builder 包含一个用于创建此列的辅助方法：

php

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::table('flights', function (Blueprint $table) {
    $table->softDeletes();
});

Schema::table('flights', function (Blueprint $table) {
    $table->dropSoftDeletes();
});

现在，当您在模型上调用 delete 方法时，deleted_at 列将被设置为当前日期和时间。然而，模型的数据库记录将保留在表中。当查询使用软删除的模型时，软删除的模型将自动从所有查询结果中排除。

要确定给定的模型实例是否已被软删除，您可以使用 trashed 方法：

php

if ($flight->trashed()) {
    // ...
}

恢复软删除的模型

有时您可能希望“取消删除”一个软删除的模型。要恢复一个软删除的模型，您可以在模型实例上调用 restore 方法。restore 方法将模型的 deleted_at 列设置为 null：

php

$flight->restore();

您还可以在查询中使用 restore 方法来恢复多个模型。同样，像其他“批量”操作一样，这不会为恢复的模型调度任何模型事件：

php

Flight::withTrashed()
    ->where('airline_id', 1)
    ->restore();

restore 方法也可以在构建关系查询时使用：

php

$flight->history()->restore();

永久删除模型

有时您可能需要真正从数据库中删除一个模型。您可以使用 forceDelete 方法从数据库表中永久删除一个软删除的模型：

php

$flight->forceDelete();

您还可以在构建 Eloquent 关系查询时使用 forceDelete 方法：

php

$flight->history()->forceDelete();

查询软删除的模型

包含软删除的模型

如上所述，软删除的模型将自动从查询结果中排除。然而，您可以通过在查询上调用 withTrashed 方法来强制将软删除的模型包含在查询结果中：

php

use App\Models\Flight;

$flights = Flight::withTrashed()
    ->where('account_id', 1)
    ->get();

withTrashed 方法也可以在构建关系查询时调用：

php

$flight->history()->withTrashed()->get();

仅检索软删除的模型

onlyTrashed 方法将仅检索软删除的模型：

php

$flights = Flight::onlyTrashed()
    ->where('airline_id', 1)
    ->get();

修剪模型

有时您可能希望定期删除不再需要的模型。为此，您可以将 Illuminate\Database\Eloquent\Prunable 或 Illuminate\Database\Eloquent\MassPrunable trait 添加到您希望定期修剪的模型中。在将其中一个 trait 添加到模型后，实现一个 prunable 方法，该方法返回一个 Eloquent 查询构建器，用于解析不再需要的模型：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Prunable;

class Flight extends Model
{
    use Prunable;

    /**
     * 获取可修剪的模型查询。
     */
    public function prunable(): Builder
    {
        return static::where('created_at', '<=', now()->subMonth());
    }
}

在将模型标记为 Prunable 时，您还可以在模型上定义一个 pruning 方法。此方法将在模型被删除之前调用。此方法对于在模型从数据库中永久删除之前删除与模型关联的任何其他资源（如存储的文件）非常有用：

php

/**
 * 准备模型进行修剪。
 */
protected function pruning(): void
{
    // ...
}

在配置好您的可修剪模型后，您应该在应用程序的 routes/console.php 文件中调度 model:prune Artisan 命令。您可以自由选择此命令应运行的适当间隔：

php

use Illuminate\Support\Facades\Schedule;

Schedule::command('model:prune')->daily();

在后台，model:prune 命令将自动检测应用程序 app/Models 目录中的“可修剪”模型。如果您的模型位于其他位置，您可以使用 --model 选项指定模型类名：

php

Schedule::command('model:prune', [
    '--model' => [Address::class, Flight::class],
])->daily();

如果您希望在修剪所有其他检测到的模型时排除某些模型，您可以使用 --except 选项：

php

Schedule::command('model:prune', [
    '--except' => [Address::class, Flight::class],
])->daily();

您可以通过执行带有 --pretend 选项的 model:prune 命令来测试您的 prunable 查询。在假装时，model:prune 命令将仅报告如果命令实际运行将修剪多少记录：

shell

php artisan model:prune --pretend

WARNING

如果软删除的模型符合可修剪查询，它们将被永久删除（forceDelete）。

批量修剪

当模型标记为 Illuminate\Database\Eloquent\MassPrunable trait 时，模型将使用批量删除查询从数据库中删除。因此，pruning 方法将不会被调用，deleting 和 deleted 模型事件也不会被调度。这是因为在删除之前模型实际上从未被检索，从而使修剪过程更加高效：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\MassPrunable;

class Flight extends Model
{
    use MassPrunable;

    /**
     * 获取可修剪的模型查询。
     */
    public function prunable(): Builder
    {
        return static::where('created_at', '<=', now()->subMonth());
    }
}

复制模型

您可以使用 replicate 方法创建现有模型实例的未保存副本。当您有许多共享相同属性的模型实例时，此方法特别有用：

php

use App\Models\Address;

$shipping = Address::create([
    'type' => 'shipping',
    'line_1' => '123 Example Street',
    'city' => 'Victorville',
    'state' => 'CA',
    'postcode' => '90001',
]);

$billing = $shipping->replicate()->fill([
    'type' => 'billing'
]);

$billing->save();

要排除一个或多个属性不被复制到新模型中，您可以将一个数组传递给 replicate 方法：

php

$flight = Flight::create([
    'destination' => 'LAX',
    'origin' => 'LHR',
    'last_flown' => '2020-03-04 11:00:00',
    'last_pilot_id' => 747,
]);

$flight = $flight->replicate([
    'last_flown',
    'last_pilot_id'
]);

查询范围

全局范围

全局范围允许您为给定模型的所有查询添加约束。Laravel 自己的软删除功能利用全局范围仅从数据库中检索“未删除”的模型。编写您自己的全局范围可以提供一种方便、简单的方法来确保给定模型的每个查询都接收到某些约束。

生成范围

要生成新的全局范围，您可以调用 make:scope Artisan 命令，该命令会将生成的范围放置在应用程序的 app/Models/Scopes 目录中：

shell

php artisan make:scope AncientScope

编写全局范围

编写全局范围很简单。首先，使用 make:scope 命令生成一个实现 Illuminate\Database\Eloquent\Scope 接口的类。Scope 接口要求您实现一个方法：apply。apply 方法可以根据需要向查询添加 where 约束或其他类型的子句：

php

<?php

namespace App\Models\Scopes;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;

class AncientScope implements Scope
{
    /**
     * 将范围应用于给定的 Eloquent 查询构建器。
     */
    public function apply(Builder $builder, Model $model): void
    {
        $builder->where('created_at', '<', now()->subYears(2000));
    }
}

NOTE

如果您的全局范围正在向查询的 select 子句添加列，您应该使用 addSelect 方法而不是 select。这将防止无意中替换查询的现有 select 子句。

应用全局范围

要将全局范围分配给模型，您可以简单地将 ScopedBy 属性放在模型上：

php

<?php

namespace App\Models;

use App\Models\Scopes\AncientScope;
use Illuminate\Database\Eloquent\Attributes\ScopedBy;

#[ScopedBy([AncientScope::class])]
class User extends Model
{
    //
}

或者，您可以通过重写模型的 booted 方法并调用模型的 addGlobalScope 方法手动注册全局范围。addGlobalScope 方法接受您的范围实例作为其唯一参数：

php

<?php

namespace App\Models;

use App\Models\Scopes\AncientScope;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 模型的“booted”方法。
     */
    protected static function booted(): void
    {
        static::addGlobalScope(new AncientScope);
    }
}

在将上面示例中的范围添加到 App\Models\User 模型后，调用 User::all() 方法将执行以下 SQL 查询：

sql

select * from `users` where `created_at` < 0021-02-18 00:00:00

匿名全局范围

Eloquent 还允许您使用闭包定义全局范围，这对于不需要单独类的简单范围特别有用。使用闭包定义全局范围时，您应该为 addGlobalScope 方法提供一个您自己选择的范围名称作为第一个参数：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 模型的“booted”方法。
     */
    protected static function booted(): void
    {
        static::addGlobalScope('ancient', function (Builder $builder) {
            $builder->where('created_at', '<', now()->subYears(2000));
        });
    }
}

移除全局范围

如果您希望为给定查询移除全局范围，可以使用 withoutGlobalScope 方法。此方法接受全局范围的类名作为其唯一参数：

php

User::withoutGlobalScope(AncientScope::class)->get();

或者，如果您使用闭包定义了全局范围，您应该传递您分配给全局范围的字符串名称：

php

User::withoutGlobalScope('ancient')->get();

如果您希望移除多个甚至所有查询的全局范围，可以使用 withoutGlobalScopes 方法：

php

// 移除所有全局范围...
User::withoutGlobalScopes()->get();

// 移除某些全局范围...
User::withoutGlobalScopes([
    FirstScope::class, SecondScope::class
])->get();

本地范围

本地作用域允许你定义一组常见的查询约束，以便在应用程序中轻松复用。例如，你可能需要频繁检索所有被认为是“热门”的用户。要定义一个作用域，可以在 Eloquent 方法上添加 Scope 属性。

范围应始终返回相同的查询构建器实例或 void：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Scope;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 将查询范围限定为仅包含受欢迎的用户。
     */
    #[Scope]
    protected function popular(Builder $query): void
    {
        $query->where('votes', '>', 100);
    }

    /**
     * 将查询范围限定为仅包含活跃用户。
     */
    #[Scope]
    protected function active(Builder $query): void
    {
        $query->where('active', 1);
    }
}

使用本地范围

一旦定义了作用域，你可以在查询模型时调用该作用域方法。你甚至可以链式调用多个作用域：

php

use App\Models\User;

$users = User::popular()->active()->orderBy('created_at')->get();

通过 or 查询运算符组合多个 Eloquent 模型范围可能需要使用闭包来实现正确的逻辑分组：

php

$users = User::popular()->orWhere(function (Builder $query) {
    $query->active();
})->get();

然而，由于这可能很麻烦，Laravel 提供了一个“高阶” orWhere 方法，允许您在不使用闭包的情况下流畅地链式调用范围：

php

$users = User::popular()->orWhere->active()->get();

动态范围

有时您可能希望定义一个接受参数的范围。要开始，只需将您的附加参数添加到范围方法的签名中。范围参数应在 $query 参数之后定义：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Scope;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 将查询范围限定为仅包含给定类型的用户。
     */
    #[Scope]
    protected function ofType(Builder $query, string $type): void
    {
        $query->where('type', $type);
    }
}

一旦将预期参数添加到范围方法的签名中，您可以在调用范围时传递参数：

php

$users = User::ofType('admin')->get();

待定属性

如果您希望使用范围创建具有与约束范围相同属性的模型，可以在构建范围查询时使用 withAttributes 方法：

php

<?php

namespace App\Models;

use Illuminate\Database\Attributes\Scope;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    /**
     * 将查询范围限定为仅包含草稿。
     */
    #[Scope]
    protected function draft(Builder $query): void
    {
        $query->withAttributes([
            'hidden' => true,
        ]);
    }
}

withAttributes 方法将使用给定的属性向查询添加 where 条件，并且还会将这些属性添加到通过作用域创建的任何模型中：

php

$draft = Post::draft()->create(['title' => 'In Progress']);

$draft->hidden; // true

要指示 withAttributes 方法不要向查询添加 where 条件，可以将 asConditions 参数设置为 false：

php

$query->withAttributes([
    'hidden' => true,
], asConditions: false);

比较模型

有时您可能需要确定两个模型是否“相同”。is 和 isNot 方法可以快速验证两个模型是否具有相同的主键、表和数据库连接：

php

if ($post->is($anotherPost)) {
    // ...
}

if ($post->isNot($anotherPost)) {
    // ...
}

is 和 isNot 方法在使用 belongsTo、hasOne、morphTo 和 morphOne 关系时也可用。当您希望在不发出查询以检索该模型的情况下比较相关模型时，此方法特别有用：

php

if ($post->author()->is($user)) {
    // ...
}

事件

NOTE

想要将您的 Eloquent 事件直接广播到客户端应用程序？请查看 Laravel 的模型事件广播。

Eloquent 模型会调度多个事件，允许您在模型生命周期的以下时刻进行挂钩：retrieved、creating、created、updating、updated、saving、saved、deleting、deleted、trashed、forceDeleting、forceDeleted、restoring、restored 和 replicating。

retrieved 事件将在从数据库中检索现有模型时调度。当新模型首次保存时，将调度 creating 和 created 事件。updating / updated 事件将在修改现有模型并调用 save 方法时调度。saving / saved 事件将在创建或更新模型时调度，即使模型的属性没有更改。以 -ing 结尾的事件在对模型的更改持久化之前调度，而以 -ed 结尾的事件在对模型的更改持久化之后调度。

要开始监听模型事件，请在 Eloquent 模型上定义一个 $dispatchesEvents 属性。此属性将 Eloquent 模型生命周期的各个点映射到您自己的事件类。每个模型事件类应期望通过其构造函数接收受影响的模型实例：

php

<?php

namespace App\Models;

use App\Events\UserDeleted;
use App\Events\UserSaved;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;

    /**
     * 模型的事件映射。
     *
     * @var array<string, string>
     */
    protected $dispatchesEvents = [
        'saved' => UserSaved::class,
        'deleted' => UserDeleted::class,
    ];
}

在定义和映射您的 Eloquent 事件后，您可以使用事件监听器来处理事件。

WARNING

当通过 Eloquent 发出批量更新或删除查询时，saved、updated、deleting 和 deleted 模型事件将不会为受影响的模型调度。这是因为在执行批量更新或删除时，模型实际上从未被检索。

使用闭包

您可以注册在调度各种模型事件时执行的闭包，而不是使用自定义事件类。通常，您应该在模型的 booted 方法中注册这些闭包：

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 模型的“booted”方法。
     */
    protected static function booted(): void
    {
        static::created(function (User $user) {
            // ...
        });
    }
}

如果需要，您可以在注册模型事件时使用可排队的匿名事件监听器。这将指示 Laravel 使用应用程序的队列在后台执行模型事件监听器：

php

use function Illuminate\Events\queueable;

static::created(queueable(function (User $user) {
    // ...
}));

观察者

定义观察者

如果您正在监听给定模型上的许多事件，您可以使用观察者将所有监听器分组到一个类中。观察者类具有反映您希望监听的 Eloquent 事件的方法名称。每个方法接收受影响的模型作为其唯一参数。make:observer Artisan 命令是创建新观察者类的最简单方法：

shell

php artisan make:observer UserObserver --model=User

此命令会将新观察者放置在您的 app/Observers 目录中。如果此目录不存在，Artisan 将为您创建它。您的新观察者将如下所示：

php

<?php

namespace App\Observers;

use App\Models\User;

class UserObserver
{
    /**
     * 处理 User "created" 事件。
     */
    public function created(User $user): void
    {
        // ...
    }

    /**
     * 处理 User "updated" 事件。
     */
    public function updated(User $user): void
    {
        // ...
    }

    /**
     * 处理 User "deleted" 事件。
     */
    public function deleted(User $user): void
    {
        // ...
    }

    /**
     * 处理 User "restored" 事件。
     */
    public function restored(User $user): void
    {
        // ...
    }

    /**
     * 处理 User "forceDeleted" 事件。
     */
    public function forceDeleted(User $user): void
    {
        // ...
    }
}

要注册观察者，您可以将 ObservedBy 属性放在相应的模型上：

php

use App\Observers\UserObserver;
use Illuminate\Database\Eloquent\Attributes\ObservedBy;

#[ObservedBy([UserObserver::class])]
class User extends Authenticatable
{
    //
}

或者，您可以通过调用您希望观察的模型上的 observe 方法手动注册观察者。您可以在应用程序的 AppServiceProvider 类的 boot 方法中注册观察者：

php

use App\Models\User;
use App\Observers\UserObserver;

/**
 * 启动任何应用程序服务。
 */
public function boot(): void
{
    User::observe(UserObserver::class);
}

NOTE

观察者可以监听其他事件，如 saving 和 retrieved。这些事件在事件文档中描述。

观察者和数据库事务

当模型在数据库事务中创建时，您可能希望指示观察者仅在数据库事务提交后执行其事件处理程序。您可以通过在观察者上实现 ShouldHandleEventsAfterCommit 接口来实现此目的。如果数据库事务未进行，事件处理程序将立即执行：

php

<?php

namespace App\Observers;

use App\Models\User;
use Illuminate\Contracts\Events\ShouldHandleEventsAfterCommit;

class UserObserver implements ShouldHandleEventsAfterCommit
{
    /**
     * 处理 User "created" 事件。
     */
    public function created(User $user): void
    {
        // ...
    }
}

静音事件

您可能偶尔需要暂时“静音”模型触发的所有事件。您可以使用 withoutEvents 方法实现此目的。withoutEvents 方法接受一个闭包作为其唯一参数。在此闭包中执行的任何代码都不会调度模型事件，并且闭包返回的任何值都将由 withoutEvents 方法返回：

php

use App\Models\User;

$user = User::withoutEvents(function () {
    User::findOrFail(1)->delete();

    return User::find(2);
});

保存单个模型而不触发事件

有时您可能希望“保存”给定模型而不调度任何事件。您可以使用 saveQuietly 方法实现此目的：

php

$user = User::findOrFail(1);

$user->name = 'Victoria Faith';

$user->saveQuietly();

您还可以“更新”、“删除”、“软删除”、“恢复”和“复制”给定模型而不调度任何事件：

php

$user->deleteQuietly();
$user->forceDeleteQuietly();
$user->restoreQuietly();

Eloquent: 入门 ​

介绍 ​

生成模型类 ​

检查模型 ​

Eloquent 模型约定 ​

表名 ​

主键 ​

“复合”主键 ​

UUID 和 ULID 键 ​

时间戳 ​

数据库连接 ​

默认属性值 ​

配置 Eloquent 严格性 ​

检索模型 ​

构建查询 ​

刷新模型 ​

集合 ​

分块结果 ​

使用惰性集合分块 ​

游标 ​

高级子查询 ​

子查询选择 ​

子查询排序 ​

检索单个模型/聚合 ​

未找到异常 ​

检索或创建模型 ​

检索聚合 ​

插入和更新模型 ​

插入 ​

更新 ​

批量更新 ​

检查属性更改 ​

批量赋值 ​

批量赋值和 JSON 列 ​

允许批量赋值 ​

批量赋值异常 ​

Upserts ​

删除模型 ​

通过主键删除现有模型 ​

使用查询删除模型 ​

软删除 ​

恢复软删除的模型 ​

永久删除模型 ​

查询软删除的模型 ​

包含软删除的模型 ​

仅检索软删除的模型 ​

修剪模型 ​

批量修剪 ​

复制模型 ​

查询范围 ​

全局范围 ​

生成范围 ​

编写全局范围 ​

应用全局范围 ​

匿名全局范围 ​

移除全局范围 ​

本地范围 ​

使用本地范围 ​

动态范围 ​

待定属性 ​

比较模型 ​

事件 ​

使用闭包 ​

观察者 ​

定义观察者 ​

观察者和数据库事务 ​

静音事件 ​

保存单个模型而不触发事件 ​

Eloquent: 入门

介绍

生成模型类

检查模型

Eloquent 模型约定

表名

主键

“复合”主键

UUID 和 ULID 键

时间戳

数据库连接

默认属性值

配置 Eloquent 严格性

检索模型

构建查询

刷新模型

集合

分块结果

使用惰性集合分块

游标

高级子查询

子查询选择

子查询排序

检索单个模型/聚合

未找到异常

检索或创建模型

检索聚合

插入和更新模型

插入

更新

批量更新

检查属性更改

批量赋值

批量赋值和 JSON 列

允许批量赋值

批量赋值异常

Upserts

删除模型

通过主键删除现有模型

使用查询删除模型

软删除

恢复软删除的模型

永久删除模型

查询软删除的模型

包含软删除的模型

仅检索软删除的模型

修剪模型

批量修剪

复制模型

查询范围

全局范围

生成范围

编写全局范围

应用全局范围

匿名全局范围

移除全局范围

本地范围

使用本地范围

动态范围

待定属性

比较模型

事件

使用闭包

观察者

定义观察者

观察者和数据库事务

静音事件

保存单个模型而不触发事件