Laravel 模型事件入门

image.png

Laravel 模型事件允许你监听模型生命周期内的多个关键点,甚至可以在阻止一个模型的保存或者删除。 Laravel 模型事件文档 概述了如何使用钩子将对应事件与相关的事件类型关联起来,但是本文的主旨是事件与监听器的构建与设置,并额外补充一些细节的说明。

事件概述

Eloquent 有很多事件可以让你使用钩子将它们关联起来,并且增加自定义的功能到你的模型中。该模型起始时有以下事件:

  • retrieved
  • creating
  • created
  • updating
  • updated
  • saving
  • saved
  • deleting
  • deleted
  • restoring
  • restored

从文档这里我们可以了解它们都是如何实现的,你还可以进入 Model 的基类去看看它们到底是如何实现的:

当现有模型被数据库检索时, retrieved 事件将会触发。当一个新的模型被第一次保存时, creatingcreated 事件将会触发。如果对一个已经存在于数据库的模型调用 save 方法, updating / updated 事件将会触发。无论怎样,在这两种情况下, saving / saved 事件都会触发。

文档中对模型事件进行了很好的概述,同时解释了怎样使用钩子去关联事件,但是如果你是初学者,或者并不是熟悉怎样使用钩子将事件监听器与这些自定义模型事件相关联,请进一步阅读本文。

注册 事件

为了在你的模型中关联一个事件,你需要做的第一件事是使用 $dispatchesEvents 属性去注册事件对象,这最终将通过 HasEvents::fireCustomModelEvent() 方法触发, 该方法将通过 fireModelEvent() 方法被调用。 fireCustomModelEvent() 方法原始的时候大致是下面这样:

/**
 * 为给定的事件触发一个自定义模型。
 *
 * @param  string  $event
 * @param  string  $method
 * @return mixed|null
 */
protected function fireCustomModelEvent($event, $method)
{
    if (! isset($this->dispatchesEvents[$event])) {
        return;
    }

    $result = static::$dispatcher->$method(new $this->dispatchesEvents[$event]($this));

    if (! is_null($result)) {
        return $result;
    }
}

一些事件,比如 delete, 将进行检测判断是否这个事件会返回 false 然后退出操作。比如,你可以使用这个钩子去做一些检测,也可以防止一个用户被创建或删除。

使用 App\User 模型举例, 这里展示了如何配置你的模型事件:

protected $dispatchesEvents = [
    'saving' => \App\Events\UserSaving::class,
];

你可以使用 artisan make:event 命令来为你创建这个事件, 但基本上这将是你最后得到结果 :

<?php

namespace App\Events;

use App\User;
use Illuminate\Queue\SerializesModels;

class UserSaving
{
    use SerializesModels;

    public $user;

    /**
     *  创建一个新的事件实例
     *
     * @param \App\User $user
     */
    public function __construct(User $user)
    {
        $this->user = $user;
    }
}

我们的事件提供了一个公有的 $user 属性以便你能够在 saving事件期间访问 User模型实例。

为了让它工作起来下一步需要做的是为这个事件建立一个实际的监听器。我们设置好模型的触发时机,当 User模型触发 saving 事件,监听器就会被调。

创建一个事件监听器

现在,我们定义 User 模型并注册一个事件监听器来监听 saving 事件的触发。虽然,我能通过模型观察器快速实现,但是,我想引导你为单个事件触发配置事件监听器。

事件监听器就像 Laravel 其它事件监听一样,handle() 方法将接收 App\Events\UserSaving 事件类的一个实例。

你可以手动创建它,也可以使用 php artisan make:listener 命令。 不管怎么样,你都将创建一个像下面这样子监听类:

<?php

namespace App\Listeners;

use App\Events\UserSaving as UserSavingEvent;

class UserSaving
{
    /**
     * 处理事件。
     *
     * @param  \App\Events\UserSavingEvent $event
     * @return mixed
     */
    public function handle(UserSavingEvent $event)
    {
        app('log')->info($event->user);
    }
}

我只是添加了一个日志记录调用,以便于检查传递给监听器的模型。为此,我们还需要在 EventServiceProvider::$listen 属性中注册监听器:

<?php

namespace App\Providers;

use Illuminate\Support\Facades\Event;
use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;

class EventServiceProvider extends ServiceProvider
{
    /**
     * 应用的事件监听器。
     * 
     * @var array
     */
    protected $listen = [
        \App\Events\UserSaving::class => [
            \App\Listeners\UserSaving::class,
        ],
    ];

    // ...
}

现在,当模型调用 saving 事件时,我们注册的事件监听器也会被触发并执行。

尝试事件监听

我们可以通过 tinker 会话快速生成事件监听代码:

php artisan tinker
>>> factory(\App\User::class)->create();
=> App\User {#794
     name: "Aiden Cremin",
     email: "josie05@example.com",
     updated_at: "2018-03-15 03:57:18",
     created_at: "2018-03-15 03:57:18",
     id: 2,
   }

如果你已正确注册了事件和监听器,则应该在 laravel.log 文件中可以看到该模型的 JSON 表达形式:

[2018-03-15 03:57:18] local.INFO: {"name":"Aiden Cremin","email":"josie05@example.com"}

要注意的一点,此时模型并没有 created_atupdated_at 属性。如果在模型上再次调用 save() ,日志上将会有一个带有时间戳的新记录,因为 saving 事件会在新创建的记录或现在有记录上触发:

>>> $u = factory(\App\User::class)->create();
=> App\User {#741
     name: "Eloisa Hirthe",
     email: "gottlieb.itzel@example.com",
     updated_at: "2018-03-15 03:59:37",
     created_at: "2018-03-15 03:59:37",
     id: 3,
   }
>>> $u->save();
=> true
>>>

停止一个保存操作

某些模型事件是允许你进行阻止操作的。举个荒谬的例子,假设我们不允许任何一个用户的模型保存其属性 $user->name 的内容为 Paul

/**
 * 处理事件。
 *
 * @param  \App\Events\UserSaving $event
 * @return mixed
 */
public function handle(UserSaving $event)
{
    if (stripos($event->user->name, 'paul') !== false) {
        return false;
    }
}

在 Eloquent 的 Model::save() 方法中,会根据事件监听的返回结果判断是否进行停止保存操作:

public function save(array $options = [])
{
    $query = $this->newQueryWithoutScopes();

    // 如果 "saving" 事件返回 false ,我们将退出保存并返回
    // false,表示保存失败。这为服务监听者提供了一个机会,
    // 当验证失败或者出现其它任何情况,都可以取消保存操作。
    if ($this->fireModelEvent('saving') === false) {
        return false;
    }

这个 save() 是个很好的例子,它告诉了你如何在模型生命周期中自定义事件,以及被动执行日志数据记录或者任务调度。

使用观察者

如果你正在监听多个事件,那么你可能会发现使用观察者类来按类型分组存放事件会更加方便。这里是一个例子 Eloquent 观察者

<?php

namespace App\Observers;

use App\User;

class UserObserver
{
    /**
     * 监听 User 创建事件。
     *
     * @param  \App\User  $user
     * @return void
     */
    public function created(User $user)
    {
        //
    }

    /**
     * 监听 User 删除事件。
     *
     * @param  \App\User  $user
     * @return void
     */
    public function deleting(User $user)
    {
        //
    }
}

你可以在服务提供者 AppServiceProvider 中的 boot() 方法里注册观察者。

/**
 * 运行所有应用服务。
 *
 * @return void
 */
public function boot()
{
    User::observe(UserObserver::class);
}

了解更多

我建议你阅读 Laravel 事件文档 去了解有关事件和监听器在整个框架中如何工作。 Eloquent 事件文档 对于可用事件以及如何使用观察者是一个非常好的参考。最后,我建议浏览 Illuminate\Database\Eloquent\Model 类来查找 fireModelEvent() 方法调用的用法去了解事件如何与模型和 HasEvents trait 将这些事件联系在一起。

现代化 PHP 知识日新月异,尤其是 PHP7 出来以后,欢迎加入 PHP / Laravel 知识社区 一起成长。

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 201,784评论 5 474
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 84,745评论 2 378
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 148,702评论 0 335
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 54,229评论 1 272
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 63,245评论 5 363
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,376评论 1 281
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 37,798评论 3 393
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,471评论 0 256
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 40,655评论 1 295
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,485评论 2 318
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,535评论 1 329
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,235评论 3 318
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 38,793评论 3 304
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,863评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,096评论 1 258
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 42,654评论 2 348
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,233评论 2 341

推荐阅读更多精彩内容