Events

• Registering Event Listeners
• \MVC\Event::run()
• \MVC\Event::bind()
  • bind to an Event Name
  • bind to an Event Name with placeholder
  • bind to a Controller::method
  • Additional Context Infos passed as second parameter to a bonded closure
  • Bind to Events via config Stack with \MVC\Event::processBindConfigStack()
• \MVC\Event::delete()
• Emvicy Standard Events
  • Database Events
• Examples
  • Chained Events

Registering Event Listeners

Location where to write Event Listeners

module/{module}/etc/event/

Listeners written here are executed right after all Configurations have been loaded. No essential classes of Emvicy have been loaded or processed at this point yet.

So this is the perfect place to influence the behavior of the starting application.

Example: log current request object to debug.log when on develop environment

<?php

\MVC\Event::processBindConfigStack([

    /**
     * after current request was get
     */
    'mvc.request.in.after' => [
        /*
         * logging requests
         */
        function(\MVC\DataType\DTRequestIn $oDTRequestIn, \MVC\DataType\DTEventContext $oDTEventContext) {

            if (false === \MVC\Config::get_MVC_LOG_REQUEST())
            {
                return false;
            }

            \MVC\Log::write(php_sapi_name () . ' ' . $oDTRequestIn->get_requestMethod() . ' ' . $oDTRequestIn->get_full(), \MVC\Config::get_MVC_LOG_FILE_REQUEST());
        },
    ],
]);

You can write your own event bondings into an already existing file.

And you may add as many events as your application requires.

You can also create your own php file in that folder and note your event bondings, no problem.
⚠ but consider the loading order of the files, which is a-z.

\MVC\Event::run()

with run you initialize an event; bonded Closures to the event name get executed in order.

Syntax

\MVC\Event::run('eventName', {mixed} );

Example: Run a simple Event

\MVC\Event::run('foo');

Example: pass a value to the event

\MVC\Event::run('foo', 123);

Example: pass an DTArrayObject Object with Infos

\MVC\Event::run('foo', DTArrayObject::create()
    ->add_aKeyValue(
        DTKeyValue::create()->set_sKey('foo')->set_sValue('bar')
    )
);

\MVC\Event::bind()

with bind you create a Listener to an expected event; you bind a closure to the expected event.

Syntax

\MVC\Event::bind('event', {closure} );

bind to an Event Name

regular - listens to event whose event name is 'fooName'

\MVC\Event::bind('fooName', function() { ... });

bind to an Event Name with placeholder

you can listen for many similar events by using wildcard symbol * (asterisk).

Examples: with placeholder * - listens to all events whose event names match

// listen for events that begin with `foo`
\MVC\Event::bind('foo*', function() { ... });

// listen for events ending with `Name`
\MVC\Event::bind('*Name', function() { ... });

// listens for events that begin with "f" and have an "N" somewhere in between
\MVC\Event::bind('f*N*', function() { ... });

// listen for events that begin with `mvc.db.model.` and end with `.sql`
\MVC\Event::bind('mvc.db.model.*.sql', function() { ... }); 

bind to a Controller::method

Example: bind a closure to a concrete Controller::method

\MVC\Event::bind('\Foo\Controller\Index::foo', function (\MVC\DataType\DTArrayObject $oDTArrayObject, \MVC\DataType\DTEventContext $oDTEventContext) {
    info($oDTArrayObject);
    display($oDTEventContext);
});

• 🛈 The first parameter will always be of type \MVC\DataType\DTArrayObject $oDTArrayObject
• 🛈 You can bind to Controller classes only which have \MVC\MVCInterface\Controller implemented
• 🛈 Make sure to write the event name as the method was a static one, even it is not.

Additional Context Infos passed as second parameter to a bonded closure

As you may have noticed, the object \MVC\DataType\DTEventContext $oDTEventContext) is always being passed as the second parameter to a bonded closure. It provides Infos about the context of the event.

This is helpful if your app listens to events with placeholder * - let's say foo* (with placeholder asterisk). You can get the origin Event which matched to foo*:

// returns 'fooName'
$oDTEventContext->get_sEventOrigin();

example content of \MVC\DataType\DTEventContext $oDTEventContext)

// type: object
\MVC\DataType\DTEventContext::__set_state(array(
      'sEvent' => 'foo*',
      'sEventOrigin' => 'fooName',
      'mRunPackage' => true,
      'aBonded' =>    array (
        's:53:"/modules/{module}/etc/event/default.php, 7 (65759f7544778)";' =>        \Closure::__set_state(array(
        )),
    ),
      'sBondedBy' => 's:53:"/modules/{module}/etc/event/default.php, 7 (65759f7544778)";',
      'sCalledIn' => '/modules/Foo/Controller/Index.php, 58',
      'oCallback' =>    \Closure::__set_state(array(
    )),
      'sCallbackDumped' => 'function (oDTEventContext $oDTEventContext){
                        info($oDTEventContext);
                        display($oDTEventContext->get_sEventOrigin());
                },
',
      'sMessage' => 'RUN+ (foo* [fooName]) --> called in: /modules/Foo/Controller/Index.php, 58 --> bonded by `/modules/{module}/etc/event/default.php, 7 (65759f7544778), try to run its Closure: function ($mPackage, \\MVC\\DataType\\DTEventContext $oDTEventContext) { info($oDTEventContext); display($oDTEventContext->get_sEventOrigin()); }',
))

Bind to Events via config Stack with \MVC\Event::processBindConfigStack()

Instead of writing one bind command expressure after the other you can make use of array notation and use Event::processBindConfigStack.

Syntax

\MVC\Event::processBindConfigStack([ '{EventName}' => [ {Closure}, ], ]);

This way you can note bondings to multiple Events at once and you can even note multiple closures for each event.

This reduces complexity and improves readability.

Example: using config Stack to bind closures to Events

<?php
\MVC\Event::processBindConfigStack([ // Bondings to 2 Events

    '\Foo\Controller\Index::foo' => [ // 2 Closures bonded to this Event

        function (\MVC\DataType\DTArrayObject $oDTArrayObject, \MVC\DataType\DTEventContext $oDTEventContext) {      
            info($oDTArrayObject);
        },
        function (\MVC\DataType\DTArrayObject $oDTArrayObject, \MVC\DataType\DTEventContext $oDTEventContext) {      
            \MVC\Log:write($oDTArrayObject, 'debug.log');
        }
    ],
    '\Foo\Controller\Index::bar' => [ // 1 Closure bonded to this Event

        function (\MVC\DataType\DTArrayObject $oDTArrayObject, \MVC\DataType\DTEventContext $oDTEventContext) {      
            \MVC\Log:write($oDTArrayObject, 'debug.log');
        }
    ],    
]);

\MVC\Event::delete()

delete one or all events.

⚠ If this parameter not is set, all events are going to be deleted.

Example: delete the certain Event named foo.bar

\MVC\Event::delete('foo.bar');

Example: delete all Events

\MVC\Event::delete();

Emvicy Standard Events

Database Events

Examples

Chained Events

wait for database coming up before binding to one (or more) certain events

// bind to those events
\MVC\Event::processBindConfigStack([

    'mvc.db.model.dbcollection.construct.after' => [

        function () {
            // ...bind to those events
            \MVC\Event::processBindConfigStack([

                // event
                'foo.model.index.action' => [
                    function () {
                        // concrete doing
                    },
                ],
            ]);
        }
    ],
]);

wait for database coming up before binding to a certain event, run a further event when job has been done

// bind to those events
\MVC\Event::processBindConfigStack([

    // event
    'job.done' => [
        function () {
            // concrete doing
        },
    ],

    // WHEN Database has been built...
    'mvc.db.model.dbcollection.construct.after' => [

        function () {
            // ...bind to those events
            \MVC\Event::processBindConfigStack([

                // event
                'foo.model.index.action' => [
                    function () {

                        // concrete doing...

                        // run a "Job done" event
                        \MVC\Event::run('job.done', $mData);
                    },
                ],
            ]);
        }
    ],
]);