Documentation

Events
in package

A static events system.

Table of Contents

Properties

$_events  : array<string|int, array<string|int, array<string|int, callable>>>
[emitter][event] = [ listener, listener... ]
$_log  : null|array<string|int, array<string|int, array<string|int, float>>>
[emitter][event] = [ time, time... ]
$_run  : array<string|int, array<string|int, float>>
[ emitter, event ] = latest time

Methods

clearLog()  : void
Clear the event log.
getLogs()  : array<string|int, mixed>
How many times has events been triggered?
hasRun()  : bool
Has this event been triggered?
off()  : void
Remove listeners.
on()  : void
Listen to an event.
setLogging()  : void
Disable or enable event logging.
trigger()  : array<string|int, array<string|int, mixed>>
Fire an event.

Properties

$_events

[emitter][event] = [ listener, listener... ]

protected static array<string|int, array<string|int, array<string|int, callable>>> $_events = []

$_log

[emitter][event] = [ time, time... ]

protected static null|array<string|int, array<string|int, array<string|int, float>>> $_log = null

$_run

[ emitter, event ] = latest time

protected static array<string|int, array<string|int, float>> $_run = []

Methods

clearLog()

Clear the event log.

public static clearLog([bool $clearRunLog = false ]) : void
Parameters
$clearRunLog : bool = false

getLogs()

How many times has events been triggered?

public static getLogs([array<string|int, mixed> $filter = [] ]) : array<string|int, mixed>
Parameters
$filter : array<string|int, mixed> = []

[ event, sender, flatten ]

Return values
array<string|int, mixed>

hasRun()

Has this event been triggered?

public static hasRun(string $sender, EventInterface> $event) : bool
Parameters
$sender : string
$event : EventInterface>
Return values
bool

off()

Remove listeners.

public static off(class-string|object|null $sender[, EventInterface>|null $event = null ]) : void

If $event is not given (null), all listeners are removed from the sender.

Specify a null sender to remove all listeners from an event.

Or both null, null to remove all listeners from all senders.

Parameters
$sender : class-string|object|null
$event : EventInterface>|null = null

on()

Listen to an event.

public static on(class-string|object $sender, EventInterface>|callable $event[, callable|null $fn = null ][, bool $append = true ]) : void

This method has two key signatures:

// Full form
Events::on(Emitter::class, Event::class, function(MyEvent $event) });

// Short form
Events::on(Emitter::class, function(MyEvent $event) });

In the second form the event type is derived from the first parameter of the handler function.

All invocations accept the $sender as an object or string. Given a object instance the sender is attached to the event. This then automatically filters events on that sender to the appropriate instance. Filtering is not applied to EventInterface objects not extending Event.

Parameters
$sender : class-string|object
$event : EventInterface>|callable
$fn : callable|null = null
$append : bool = true
Tags
throws
InvalidArgumentException

setLogging()

Disable or enable event logging.

public static setLogging(bool $logging) : void

Default disabled.

Parameters
$logging : bool

trigger()

Fire an event.

public static trigger(class-string|object $sender, EventInterface $event[, bool $once = false ]) : array<string|int, array<string|int, mixed>>

Given a class tree like:

       Root
      /   \
    Sub   Other
    /
  Leaf

Events will propagate from their respective class subtree. Such as, 'Sub' will emit on both 'Sub' and 'Leaf', even though the class inherits from 'Root'. Whereas events from 'Root' will emit on every class.

Triggering events in a class that is not it's own, or even from a parent class is strongly discouraged.

Avoid dynamic class names, such as:

  • static::class
  • get_class($this)
Parameters
$sender : class-string|object
$event : EventInterface
$once : bool = false

Don't trigger if the event has already run at least once.

Return values
array<string|int, array<string|int, mixed>> —

event results.

On this page

Search results