Trongate Docs
switch to dark modeswitch to dark mode
»
»
Generating Tokens (PHP Friendly Version)

Generating Tokens (PHP Friendly Version)

Inside your 'modules' folder, there's a module named 'trongate_tokens'.  This module contains a controller file with a PHP class named, 'Trongate_tokens'.  This class can be used to generate security tokens.

Top Tip
The Trongate_tokens class is full of comments and has been designed to be easy to read.  It's a very good practice to become comfortable opening a file, like Trongate_tokens.php, and reading the comments to understand how the file works.

To generate security tokens, we'll be calling upon the _generate_token() method, which is inside Trongate_tokens.php.  Below is a screenshot, showing the _generate_token() method ...and just look at all those beautiful comments!

showing the _generate_token() method

Even without understanding precisely how this method works, you can clearly see - from the comments - than an array must be passed into this method in order for it to work.  You can also see, from looking at the very end of the method, that it finishes by returning a random string.  This string, of course, will be our security token.

This means that usage of the token generation feature will require PHP code that takes the following form:

$this->module('trongate_tokens');
$token = $this->trongate_tokens->_generate_token($data);

In the first line, as shown above, we are loading the trongate_tokens module.  In the second line, we are fetching a token from Trongate by passing in an argument called $data.

What's Expected From The Data Array?

When we invoke _generate_token() we have to also pass in an array of data.  This array may contain up to four properties, three of which are optional.  They are:

  • user_id (required): an integer, representing the trongate_user_id, for the user who is to receive a token
  • expiry_date (optional): a Unix timestamp that represents the token expiry date
  • set_cookie (optional): a boolean where true indicates that you'd like PHP to generate a cookie for the user
  • code (optional): if you submit a code property with a value of 'aaa', it means that your token will grant full access, regardless of the user's role.  This feature gets used in the API manager but - in practice - it's very unlikely that you'll ever have a need to manually generate a token with a 'aaa' code.

Did You Know?
If you do not submit a token expiry date, Trongate will use the default token lifespan as a fallback.  The default token lifespan is set at the top of the Trongate_tokens class and it has a value of 86400 seconds (i.e., one day).

Top Tip
If you use PHP's time() function, you can generate a Unix timestamp that represents now.  Combining the time() function with a little arithmetic can allow us to easily generate meaningful expiry dates in PHP.  For example, there are 86,400 seconds in a day.  To get an expiry date that is three days into the future we could say:

$data['expiry_date'] = time() + (86400*3);

Below is an example of token generation, using the Trongate_tokens class:

$data['user_id'] = 88; //the id from trongate_users
$data['expiry_date'] = time() + (86400*7); //one week
$data['set_cookie'] = true; //requesting cookie generation

//load trongate_tokens module
$this->module('trongate_tokens');

//generate a token
$this->trongate_tokens->_generate_token($data);


Just To Let You Know
In the code sample above, we could have concluded by fetching our token with,

$token = $this->trongate_tokens->_generate_token($data);


This would have returned our new token as a $token variable.



HELP & SUPPORT

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

 
×