Before Hooks And After Hooks - General Overview

Let's take a closer look at before hooks and after hooks.  As mentioned in the previous page, a before hook is a method that gets invoked before an inbound HTTP request is passed to the main API endpoint method.  An after hook is a method that gets invoked before an outbound HTTP response is served to the user.  

Why Would You Want To Do This?

There are a variety of situations where this kind of functionality would be useful.  A good example might be to consider the Trongate Desktop App.

The Trongate Desktop App generates complete sets of API endpoints automatically at the touch of a button.  These auto-generated endpoints can do things like; create, read, update and delete database records.  Furthermore, they are reusable.  In other words, the code inside the Trongate engine folder (specifically, Api.php) that creates records can be the same code that gets invoked for lots of different database tables.

Let's imagine that you're building a private members' website and you'd like to use Trongate's API Explorer to handle creating members' records.  Since Trongate comes with a built-in 'Create' API endpoint, we have an opportunity to save some time.   Clearly, we can use the automatically generated endpoints to create member records via either HTTP get or post requests.  It's all built-in and ready to rock.

However, suppose one of the fields that gets submitted, by new members, is 'date of birth'.  Perhaps, instead of just blindly inserting new data - into the 'members' table - maybe you'd like to jump in front of the inbound HTTP request and, by evaluating 'date of birth', make sure the new member's age is equal to or greater than sixteen.

If the end-user submits a date of birth that's below the required age then instead of proceeding with the insert, as normal, you may instead intercept the HTTP request and issue a 'not allowed' message for the end-user.  This kind of situation would be perfect for a before hook.

On the other hand, let's imagine that a member successfully joins and a new record is inserted into the database using the 'Create' endpoint.  The moment the record is inserted into the database, you may wish to send the user a confirmation email so that they can activate their membership.  So, that's two things we want to do:

• insert a new database record
• send a confirmation email

The business of inserting database records is already built into the framework, thanks to Trongate's 'Create' API endpoint.  All you would have to do, therefore, to make the insert part of the process work is make sure you have 'Create' defined within your api.json file, for the 'members' module.  However, for sending a confirmation email you could use a second method - perhaps from another module that you have written yourself. Wouldn't it be nice if we could have the email sending method being automatically invoked every time a record has been inserted into 'members'?  This would be the perfect situation for an after hook. 

//fetch posted data
$post = file_get_contents('php://input');
$data = json_decode($post, true);

//create new trongate_user record (and return id)
$this->module('trongate_users');
$trongate_user_data['code'] = make_rand_str(32);
$trongate_user_data['user_level_id'] = 2; //member
$data['trongate_user_id'] = $this->model->insert($data);

//insert the record
$data = $this->model->insert($data, 'members');