Trongate Docs
switch to dark modeswitch to dark mode
»
»
Before Hooks - Deep Dive

Before Hooks - Deep Dive

The goal of a before hook, broadly speaking, is to intercept an inbound HTTP request, do something with it, then potentially return the HTTP request to the main endpoint method.  

A before hook can be added onto an API endpoint by adding the 'beforeHook' property onto an endpoint's settings.  Below is an example of a before hook called '_check_data' being declared for a 'Get' endpoint.  This setting (which would be stored on an api.json file) would invoke a protected method named _check_data() whenever the 'Get' endpoint is invoked.  

"Get": {
  "url_segments": "api/get/fish",
  "request_type": "GET",
  "description": "Fetch rows from table",
  "enableParams": true,
  "authorization":"*",
  "beforeHook": "_check_data"
}

The Inbound Request Array

All the information that gets passed into a before hook comes in the form of an array.   We can call this array the 'inbound request array'.  

The general structure of a before hook will facilitate taking in an inbound request array, doing something with it then potentially returning the array.  If we represent our inbound request array with the variable $input, then our before hook methods can take the following form:

function _pre_insert($input) {
    //do some stuff
    return $input;
}

Diving Deeper

By using PHP's built in var_dump() method, in combination with a die statement, it's possible to explore the contents of an inbound request array.

function _pre_insert($input) {
   var_dump($input);
   die();
}

Typically, this type of exercise will reveal a variety of parameters including:

  • token - If a Trongate security token was passed into the header of the inbound HTTP request then the value of the security token will be assigned to the 'token' property of the inbound request array.  Therefore, to access the token, we could say:

$trongate_token = $input['token'];
echo $trongate_token;
die();

  • params - If parameters have been submitted, perhaps via the URL or as posted parameters, then those values will be assigned to the 'params' property.  The 'params' property is an array of key, value pairs.  For example, if 'id' with a value of '4' was posted, we could access the id with:

$id = $input['params']['id'];
echo $id; // outputs 4
die();

  • module_name - The module name will also be passed automatically into all before hooks.  For example, if a before hook is being invoked on a module named 'cars', we could display the name of the module with:

​echo $input['module_name']; //outputs 'cars'
die();

  • endpoint - Finally, the 'endpoint' name is also automatically made available on all before hooks.  An example of an endpoint name is 'Create'.  So, you could display the name of your endpoint with:

echo $input['endpoint']; //outputs (something like) 'Create'
die();

Modifying The Inbound Request Array

Having the ability to intercept inbound HTTP requests comes with a variety of advantages.  For example, it gives the developer an opportunity to run some server-side validation checks and return errors, where appropriate.

However, the real magic of before hooks is that they give the developer the ability to modify inbound data before the data reaches the main endpoint method.

FOR EXAMPLE

Let's assume that we are building a private members' website and we're going to use Trongate's inbound 'Create' method (which comes with the framework) to accept some posted data and create a new member record.

We'll assume that the data required to insert a new member record is:

  • First Name
  • Last Name
  • Email Address

These three values could be expressed in JSON like so:

{
    "first_name": "John",
    "last_name": "Smith",
    "email_address": "[email protected]"
}

Just To Let You Know
If you prefer to use camelCase, when posting JavaScript variables, then that's perfectly okay!

It's easy to visualise a form that posts these three values (perhaps using JavaScript) and sends them to an API endpoint for creating new member records.  The URL for such an endpoint may take the form of your base URL followed by api/create/members.

Instead of blindly inserting new member records into a 'members' table, it makes sense to intercept the inbound HTTP request and run some validation checks on the data before doing the insert.

Moreover, if you'd like to have your members take advantage of Trongate's inbuilt security token system, it would be a good idea to add a 'trongate_user_id' column onto your 'members' table and assign each member with a new Trongate user ID whenever new member records are created.

This may seem a little overwhelming at first.  However, if we break this into smaller steps then you'll see that it's quite easy.  The first thing we have to do, is go into the api.json file for our 'members' module and declare a before hook on the 'Create' method.  For example, the code below defines a before hook with a method named _pre_insert_actions,

  "Create": {
    "url_segments": "api/create/members",
    "request_type": "POST",
    "description": "Insert database record",
    "enableParams": true,
    "authorization": "*",
    "beforeHook": "_pre_insert_actions"
}

Just To Let You Know
You must have authorization rules declared on in-built endpoints to make them work.

With your beforeHook declared, your next goal is to build your before hook. The code for this would take following form:

function _pre_insert_action($input) {
   return $input;
}

As you can see, our before hook accepts $input as an argument.  The before hook then returns $input.  Of course, what happens in between those two events is what makes our before hook useful.

Certainly, we would want to fetch the data that has been posted.  We can do this with:

$data = $input['params'];

Next, we may wish to create a Trongate user id record before inserting a new record into the member's table.

Just To Let You Know
We are leaving out validation tests here for the purposes of clarity.  In a real world scenario, however, you should always check and filter data that has been submitted by an end user, before adding it into a database.

Top Tip
Use PDO properly and you'll never have to worry about SQL injection.  If you're not sure how to do that then simply follow this documentation to the letter.  As long as you do that, then your app will be safe from SQL injection attacks.



HELP & SUPPORT

If you have a question or a comment relating to anything you've see here, please goto the Help Bar.

 
×