Events¶
Phormium uses Événement as an event
emitter. You can access it emitter by calling Orm::emitter()
.
To subscribe to an event, call on()
method on the event emitter with the
event name as the first parameter, and the callback function as the second. The
parameters of the callback function depend on the event and are documented
below.
The Event
class provides a catalogue of all available events.
Orm::emitter()->on('query.executing' function($query, $arguments, $connection) {
// Do something
})
Query events¶
The following events are emitted when running a database query.
Event | Callback arguments | Description |
---|---|---|
Event::QUERY_STARTED | $query, $arguments, $connection | Before contacting the database. |
Event::QUERY_PREPARING | $query, $arguments, $connection | Before preparing the query. |
Event::QUERY_PREPARED | $query, $arguments, $connection | After preparing the query. |
Event::QUERY_EXECUTING | $query, $arguments, $connection | Before executing the query. |
Event::QUERY_EXECUTED | $query, $arguments, $connection | After executing the query. |
Event::QUERY_FETCHING | $query, $arguments, $connection | Before fetching resulting data. |
Event::QUERY_FETCHED | $query, $arguments, $connection, $data | After fetching resulting data. |
Event::QUERY_COMPLETED | $query, $arguments, $connection, $data | On successful completion. |
Event::QUERY_ERROR | $query, $arguments, $connection, $exception | On error. |
Note that not all events are triggered for each query. Only prepared queries will trigger preparing and prepared events. Only queries which return data will trigger fetching and fetched events.
Event callback functions use the following arguments:
Name | Type | Description |
---|---|---|
$query | string | Query SQL code |
$arguments | array | Query arguments |
$connection | Connection | Connection on which the query is run |
$data | array | The data fetched from the database. |
$exception | Exception | Exception thrown on query failure |
Transaction events¶
The following events are triggered when starting or ending a database transaction.
Event name | Description |
---|---|
Event::TRANSACTION_BEGIN | When starting a transaction. |
Event::TRANSACTION_COMMIT | When committing a transaction. |
Event::TRANSACTION_ROLLBACK | When rolling back a transaction. |
Callbacks for these events have a single argument: the
Phormium\Database\Connection
on which the action is executed.
Examples¶
Logging¶
A simple logging example using Apache log4php.
use Logger;
use Phormium\Database\Connection;
use Phormium\Event;
use Phormium\Orm;
$log = Logger::getLogger('query');
Orm::emitter()->on(Event::QUERY_STARTED, function($query, $arguments) use ($log) {
$log->info("Running query: $query");
});
Orm::emitter()->on(Event::QUERY_ERROR, function ($query, $arguments, Connection $connection, $ex) use ($log) {
$log->error("Query failed: $ex");
});
Collecting query statistics¶
Timing query execution for locating slow queries.
use Phormium\Event;
use Phormium\Orm;
class Stats
{
private $active;
private $stats = array();
/** Hooks onto relevant events. */
public function register()
{
Orm::emitter()->on(Event::QUERY_STARTED, array($this, 'started'));
Orm::emitter()->on(Event::QUERY_COMPLETED, array($this, 'completed'));
}
/** Called when a query has started. */
public function started($query, $arguments)
{
$this->active = array(
'query' => $query,
'arguments' => $arguments,
'start' => microtime(true)
);
}
/** Called when a query has completed. */
public function completed($query)
{
$active = $this->active;
$active['end'] = microtime(true);
$active['duration'] = $active['end'] - $active['start'];
$this->stats[] = $active;
$this->active = null;
}
/** Returns the collected statistics. */
public function getStats()
{
return $this->stats;
}
}
And to start collecting stats:
$stats = new Stats();
$stats->register();
Note that this example misses failed queries, which will never emit query.completed, but query.error instead.