Data Validation and Callbacks

MeekroORM lets you write methods that will run before or after a record is saved or destroyed. You can use these to validate your data, prevent the action from happening, or whatever else you might need to do. If a hook returns false or throws an exception, the action will be aborted.

Transactions for Saving and Deleting

If MeekroDB's nested transactions feature is turned on, MeekroORM will wrap saves and deletes in a transaction. This can be helpful because it allows the "post" hooks to abort actions that have saved but not yet committed. This built-in transaction won't prevent you from using transactions in your own application, since it'll only happen if nested transactions are enabled.

If you want to explicitly decide whether to have the transaction-wrapped behavior, you can set the $_use_transactions property. For example:

class Account extends MeekroORM {
  public $_use_transactions = true;
}

You could also turn it on or off for a particular transaction:

$Account->_use_transactions = false;
$Account->Save(); // without a transaction

Steps in Saving

1. You run Save()
2. MeekroORM starts transaction (if enabled)
3. _validate_[field]() runs for each field that was updated
4. _pre_save() runs
5. _pre_create() or _pre_update() runs
6. The INSERT or UPDATE happens
7. _post_create() or _post_update() runs
8. _post_save() runs
9. MeekroORM commits transaction (if enabled)
10. _post_commit() runs

Steps in Destroying

1. You run Destroy()
2. MeekroORM starts transaction (if enabled)
3. _pre_destroy() runs
4. The DELETE happens
5. _post_destroy() runs
6. MeekroORM commits transaction (if enabled)

_validate_[field]()

Runs just before the INSERT/UPDATE operation, for any fields that have been altered. It gets passed the value of the field as a parameter.

class Account extends MeekroORM {
  function _validate_email($email) {
    // this runs only if the email was changed
    if (! filter_var($email, FILTER_VALIDATE_EMAIL)) {
      return false;
    }
  }
}

$Account = Account::Load(1);
$Account->email = '[email protected]';

// will run the validate function since we changed the email
$Account->Save();

_pre_save() / _pre_create() / _pre_update()

_pre_save() runs before every save, whereas _pre_create() runs before new saves that run an INSERT and _pre_update() runs before saves of existing records that run an UPDATE.

They get passed a single parameter, which is a hash of all key/value pairs that will be inserted or updated.

class Account extends MeekroORM {
  function _pre_save($dirtyhash) {
    // validate the record here ...
  }
}

_post_save() / _post_create() / _post_update()

Similar to above, but they run just after the INSERT or UPDATE has taken place. Still, if you return false or throw an exception, the record will not be saved because our built-in transaction hasn't committed yet.

_post_commit()

Runs just after our internal transaction has COMMITted. One way this is useful is if your application includes a job queue and you want to schedule some action to be taken. This guarantees that the action will only be taken after the transaction has committed.

class Account extends MeekroORM {
  function _post_commit() {
    if (! $this->sent_welcome_email) {
      // schedules a task to happen elsewhere, guarantees that the task won't run
      // before we've COMMITted and the database record is available elsewhere
      $JobQueue->Schedule($this, 'SEND_WELCOME_EMAIL');
    }
  }
}

_pre_destroy() / _post_destroy()

Just like what we've already seen these functions run before and after the DELETE operation.