Eloquent: 入门

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

介绍

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

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

Laravel 启动营

如果您是 Laravel 新手，可以随时跳入 Laravel 启动营。Laravel 启动营将引导您使用 Eloquent 构建第一个 Laravel 应用程序。这是了解 Laravel 和 Eloquent 提供的一切的绝佳方式。

生成模型类

要开始使用，让我们创建一个 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 键

您可以选择使用 UUID 而不是自增整数作为 Eloquent 模型的主键。UUID 是通用唯一的字母数字标识符，长度为 36 个字符。

如果您希望模型使用 UUID 键而不是自增整数键，可以在模型上使用 Illuminate\Database\Eloquent\Concerns\HasUuids 特性。当然，您应该确保模型具有 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 特性将为您的模型生成 "有序" UUIDs，因为它们在索引数据库存储时更高效，因为它们可以按字典顺序排序。

您可以通过在模型上定义 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'];
}

如果愿意，您可以选择使用 ULID 而不是 UUID。ULID 类似于 UUID；但是，它们的长度仅为 26 个字符。与有序 UUID 一样，ULID 在数据库索引中是按字典顺序可排序的。要使用 ULID，您应该在模型上使用 Illuminate\Database\Eloquent\Concerns\HasUlids 特性。您还应该确保模型具有 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());
}

此外，您可以指示 Laravel 在尝试填充不可填充属性时抛出异常，通过调用 preventSilentlyDiscardingAttributes 方法。这可以帮助防止在本地开发期间尝试设置未添加到模型的 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();

由于 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 方法类似，因为它在后台以块的方式执行查询。然而，lazy 方法不会将每个块直接传递到回调中，而是返回一个扁平化的 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 模型。

由于 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\Http\Controllers\Controller;
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 且目的地为 San Diego 的航班将被标记为延迟：

php

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

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

通过 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(); // 原始属性的数组...

批量赋值

您可以使用 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 数组中的属性会被静默丢弃。在生产环境中，这是预期的行为；但是，在本地开发期间，这可能会导致对模型更改未生效的困惑。

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

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']);

除 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);

destroy 方法逐个加载每个模型并调用 delete 方法，以便为每个模型正确触发 deleting 和 deleted 事件。

使用查询删除模型

当然，您可以构建 Eloquent 查询以删除与查询条件匹配的所有模型。在此示例中，我们将删除所有标记为不活动的航班。与批量更新一样，批量删除不会为被删除的模型触发模型事件：

php

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

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

php

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

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

软删除

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

php

<?php

namespace App\Models;

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

class Flight extends Model
{
    use SoftDeletes;
}

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

您还应将 deleted_at 列添加到数据库表中。Laravel 模式构建器包含一个帮助方法来创建此列：

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 特性添加到您希望定期修剪的模型中。在将其中一个特性添加到模型后，实现一个 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

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

批量修剪

当模型标记为 Illuminate\Database\Eloquent\MassPrunable 特性时，模型将使用批量删除查询从数据库中删除。因此，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));
    }
}

如果您的全局范围正在向查询的选择子句添加列，则应使用 addSelect 方法，而不是 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
{
    /**
     * 模型的“启动”方法。
     */
    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
{
    /**
     * 模型的“启动”方法。
     */
    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\Builder;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 将查询范围限制为仅包括受欢迎的用户。
     */
    public function scopePopular(Builder $query): void
    {
        $query->where('votes', '>', 100);
    }

    /**
     * 将查询范围限制为仅包括活跃用户。
     */
    public function scopeActive(Builder $query): void
    {
        $query->where('active', 1);
    }
}

使用局部范围

定义范围后，您可以在查询模型时调用范围方法。但是，调用方法时不应包含 scope 前缀。您甚至可以将多个范围调用链接在一起：

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\Builder;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 将查询范围限制为仅包括给定类型的用户。
     */
    public function scopeOfType(Builder $query, string $type): void
    {
        $query->where('type', $type);
    }
}

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

php

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

比较模型

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

php

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

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

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

php

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

事件

想要将您的 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 事件后，您可以使用事件监听器来处理事件。

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

使用闭包

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

php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * 模型的“启动”方法。
     */
    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
{
    /**
     * 处理用户“创建”事件。
     */
    public function created(User $user): void
    {
        // ...
    }

    /**
     * 处理用户“更新”事件。
     */
    public function updated(User $user): void
    {
        // ...
    }

    /**
     * 处理用户“删除”事件。
     */
    public function deleted(User $user): void
    {
        // ...
    }

    /**
     * 处理用户“恢复”事件。
     */
    public function restored(User $user): void
    {
        // ...
    }

    /**
     * 处理用户“永久删除”事件。
     */
    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);
}

观察者可以监听的其他事件包括 saving 和 retrieved。这些事件在事件文档中进行了描述。

观察者和数据库事务

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

php

<?php

namespace App\Observers;

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

class UserObserver implements ShouldHandleEventsAfterCommit
{
    /**
     * 处理用户“创建”事件。
     */
    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: 入门 ​

介绍 ​

Laravel 启动营 ​

生成模型类 ​

检查模型 ​

Eloquent 模型约定 ​

表名 ​

主键 ​

“复合”主键 ​

UUID 和 ULID 键 ​

时间戳 ​

数据库连接 ​

默认属性值 ​

配置 Eloquent 严格性 ​

检索模型 ​

构建查询 ​

刷新模型 ​

集合 ​

分块结果 ​

使用懒集合分块 ​

游标 ​

高级子查询 ​

子查询选择 ​

子查询排序 ​

检索单个模型 / 聚合 ​

未找到异常 ​

检索或创建模型 ​

检索聚合 ​

插入和更新模型 ​

插入 ​

更新 ​

批量更新 ​

检查属性更改 ​

批量赋值 ​

批量赋值和 JSON 列 ​

允许批量赋值 ​

批量赋值异常 ​

Upserts ​

删除模型 ​

通过主键删除现有模型 ​

使用查询删除模型 ​

软删除 ​

恢复软删除的模型 ​

永久删除模型 ​

查询软删除的模型 ​

包含软删除的模型 ​

仅检索软删除的模型 ​

修剪模型 ​

批量修剪 ​

复制模型 ​

查询范围 ​

全局范围 ​

生成范围 ​

编写全局范围 ​

应用全局范围 ​

匿名全局范围 ​

移除全局范围 ​

局部范围 ​

使用局部范围 ​

动态范围 ​

比较模型 ​

事件 ​

使用闭包 ​

观察者 ​

定义观察者 ​

观察者和数据库事务 ​

静音事件 ​

在不触发事件的情况下保存单个模型 ​

Eloquent: 入门

介绍

Laravel 启动营

生成模型类

检查模型

Eloquent 模型约定

表名

主键

“复合”主键

UUID 和 ULID 键

时间戳

数据库连接

默认属性值

配置 Eloquent 严格性

检索模型

构建查询

刷新模型

集合

分块结果

使用懒集合分块

游标

高级子查询

子查询选择

子查询排序

检索单个模型 / 聚合

未找到异常

检索或创建模型

检索聚合

插入和更新模型

插入

更新

批量更新

检查属性更改

批量赋值

批量赋值和 JSON 列

允许批量赋值

批量赋值异常

Upserts

删除模型

通过主键删除现有模型

使用查询删除模型

软删除

恢复软删除的模型

永久删除模型

查询软删除的模型

包含软删除的模型

仅检索软删除的模型

修剪模型

批量修剪

复制模型

查询范围

全局范围

生成范围

编写全局范围

应用全局范围

匿名全局范围

移除全局范围

局部范围

使用局部范围

动态范围

比较模型

事件

使用闭包

观察者

定义观察者

观察者和数据库事务

静音事件

在不触发事件的情况下保存单个模型