Listeners

Tip

While CRUD provides many listeners, it’s recommended that you add your own reusable listeners for your application needs

Listeners are the foundation for the extreme flexibility Crud provides you as an application developer.

The event system allows you to hook into the most important part of the Crud actions flow and customize it to your unique application needs.

The Anatomy Of A Listener

The listener system is simply the Events System from CakePHP, and all the official documentation and usage also applies to Crud.

The Crud event system uses two methods trigger() and on() to interface the underlying CakePHP event system.

The only hard requirement for a Crud listener is that it needs to either implement the implementedEvents() method or extend \Crud\Listener\Base.

Below is the code for a simple Crud listener. In the next few sections we will walk through the code and explain how it works, and what every single line of code does.

For each section, the relevant lines of code will be highlighted.

Class And Namespace

All built-in listeners in Crud live in the Crud\Listener namespace.

All listeners in Crud, including yours, should inherit from the Crud\Listener\Base class. This class is abstract and provides numerous auxiliary methods which can be useful for you both as a developer and as an action creator.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<?php
namespace Crud\Listener;

class Example extends \Crud\Listener\BaseListener
{

    /**
     * Returns a list of all events that will fire in the lister during the Crud life-cycle.
     *
     * @return array
     */
    public function implementedEvents()
    {
        return [
            'Crud.beforeRender' => ['callable' => 'beforeRender']
        ];
    }

    /**
     * Executed when Crud.beforeRender is emitted.
     *
     * @param \Cake\Event\Event $event Event instance
     *
     * @return void
     */
    public function beforeRender(\Cake\Event\Event $event)
    {
        $this->_response()->header('X-Powered-By', 'CRUD 4.0');
    }

}

Implemented Events

As documented in the CakePHP Events System all listeners must contain a implementedEvents method.

In this example, we simply request that beforeRender in our class is executed every time a Crud.beforeRender event is emitted.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<?php
namespace Crud\Listener;

class Example extends \Crud\Listener\BaseListener
{

    /**
     * Returns a list of all events that will fire in the lister during the Crud life-cycle.
     *
     * @return array
     */
    public function implementedEvents()
    {
        return [
            'Crud.beforeRender' => ['callable' => 'beforeRender']
        ];
    }

    /**
     * Executed when Crud.beforeRender is emitted.
     *
     * @param \Cake\Event\Event $event Event instance
     *
     * @return void
     */
    public function beforeRender(\Cake\Event\Event $event)
    {
        $this->_response()->header('X-Powered-By', 'CRUD 4.0');
    }

}

Note

The Crud.beforeRender event is similar to the Controller and View event of the same name, but Crud.beforeRender is called first, and can halt the entire rendering process

The Callback

This method gets executed every time a Crud.beforeRender event is emitted from within Crud or by you as a developer. When the event is emitted, we append a header to the client HTTP response named X-Powered-By with the value CRUD 4.0.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<?php
namespace Crud\Listener;

class Example extends \Crud\Listener\BaseListener
{

    /**
     * Returns a list of all events that will fire in the lister during the Crud life-cycle.
     *
     * @return array
     */
    public function implementedEvents()
    {
        return [
            'Crud.beforeRender' => ['callable' => 'beforeRender']
        ];
    }

    /**
     * Executed when Crud.beforeRender is emitted.
     *
     * @param \Cake\Event\Event $event Event instance
     *
     * @return void
     */
    public function beforeRender(\Cake\Event\Event $event)
    {
        $this->_response()->header('X-Powered-By', 'CRUD 4.0');
    }

}

Included listeners

Crud comes with a selection of listeners covering the most common use-cases. These allow you to tap into the events within the plugin and change behavior to suit your application, or to provide extra functionality, such as an API.