2.3.4. Table Events

Each generated Table class has its own corresponding TableEvents class. The TableEvents methods are invoked automatically at different points in the Table interactions:

// runs after any Select query is created
function modifySelect(Table $table, TableSelect $select) : void

// runs after a newly-selected Row is populated
function modifySelectedRow(Table $table, Row $row) : void

// runs after any Insert query is created
function modifyInsert(Table $table, Insert $insert) : void

// runs after any Update query is created
function modifyUpdate(Table $table, Update $update) : void

// runs after any Delete query is created
function modifyDelete(Table $table, Delete $delete) : void

// runs before a Row-specific Insert query is created
function beforeInsertRow(Table $table, Row $row) : ?array

// runs after the Row-specific Insert query is created, but before it is performed
function modifyInsertRow(Table $table, Row $row, Insert $insert) : void

// runs after the Row-specific Insert query is performed
function afterInsertRow(
    Table $table,
    Row $row,
    Insert $insert,
    PDOStatement $pdoStatement
) : void

// runs before the Row-specific Update query is created
function beforeUpdateRow(Table $table, Row $row) : ?array

// runs after the Row-specific Update query is created, but before it is performed
function modifyUpdateRow(Table $table, Row $row, Update $update) : void

// runs after the Row-specific Update query is performed
function afterUpdateRow(
    Table $table,
    Row $row,
    Update $update,
    PDOStatement $pdoStatement
) : void

// runs before the Row-specific Delete query is created
function beforeDeleteRow(Table $table, Row $row) : void

// runs after the Row-specific Delete query is created, but before it is performed
function modifyDeleteRow(Table $table, Row $row, Delete $delete) : void

// runs after the Row-specific Delete query is performed
function afterDeleteRow(
    Table $table,
    Row $row,
    Delete $delete,
    PDOStatement $pdoStatement
) : void

Note:

The methods beforeInsertRow() and beforeUpdateRow() optionally return an array. If they return an array, that array's key-value pairs will be used for the insert or update. Otherwise, the difference between the Row's previous values and its current values will be calculated, and their difference will be used for the insert or update.

For example, when you call Table::updateRow(), these events run in this order:

  • beforeUpdateRow()
  • modifyUpdate()
  • modifyUpdateRow()
  • afterUpdateRow()

Note that merely calling update() to get a table-wide Update query will only run the modifyUpdate() method, as it is not a row-specific interaction.

TableEvents are the place to put behaviors such as setting inserted_at or updated_at values, etc:

namespace Blog\DataSource\Posts;

use Atlas\Table\Row;
use Atlas\Table\Table;
use Atlas\Table\TableEvents;

class PostsTableEvents extends TableEvents
{
    public function beforeInsertRow(Table $table, Row $row)
    {
        $row->inserted_at = date('Y-m-d H:i:s');
    }

    public function beforeUpdateRow(Table $table, Row $row)
    {
        $row->updated_at = date('Y-m-d H:i:s');
    }
}