1. Home
  2. Docs
  3. Rules Developer Guide
  4. Patterns & Helpers
  5. Tokenizer

Tokenizer

A rules token is a helper which takes a starting value, and translates it into another piece of data according to a provided token path. The token path is a sequence of mapped attributes (seperated by colons), that have been registered in the class map, which tells the token evaluator how to walk the data chain to translate the starting value into the final result.

MWP\Rules\ECA\Token::create( $original, $tokenPath=NULL, $argument=NULL )

/**
 * Constructor
 *
 * @param   mixed           $original       The starting value to get the token value from
 * @param   string|NULL     $tokenPath      The token path to take to get the value
 * @param   array|NULL      $argument       The starting argument definition
 */

Internally, rules uses token instances to translate user provided token strings into their corresponding values to use in rule configurations. However, they can also be used in code to derive values, and debug the class map.

@Example Code

use MWP\Rules\ECA\Token;

/* Get the year of the last post of a user given the user id */
$token = Token::create(1, 'last_post:created:gmt_year', ['class' => 'WP_User']);
$year = $token->getTokenValue();

/* or same thing, but starting with the WP_User object */
$user = get_user_by('id', 1);
$token = Token::create($user, 'last_post:created:gmt_year');
$year = $token->getTokenValue();

/* This will get the actual user object from the id */
$token = Token::create(1, '*', ['class' => 'WP_User']);
$user = $token->getTokenValue();

One important thing to note is that token values are lazy loaded. Their processing cost is not incurred until the getTokenValue() method is called for the first time. And after the token has been translated, the result is cached inside the token and will not be translated again upon further accesses.

@Debugging Tokens

It’s possible that you do not receive the value you were expecting after evaluating a token. This could be caused by a bug with your token path, or could mean that a null value was encountered during the translation and so the translation was halted.

If there is a problem with the token path itself, such as a property in the path not being defined in the class map, an ErrorException will be thrown. This indicates that the token is invalid, and the reason for why it is invalid will be contained within the exception message.

However, if there is only a problem with the values encountered during the translation, such as a null value or an unexpected data type, then the translation will be halted silently and the return value from the token will simply be NULL.

History

$token->getHistory()

A token can be debugged by looking at the token evaluation history, which is a human readable log of the steps the translation process took while walking the token path. This may help you to see where in the process your token evaluation took a wrong turn if you are getting an unexpected end result.

use MWP\Rules\ECA\Token;

/* Get the year of the last post of a user given the user id */
$token = Token::create( 'whoops', 'last_post:created:gmt_year', ['class' => 'WP_User'] );
$year = $token->getTokenValue();

print "<pre>";
print_r( $token->getHistory() );
Was this article helpful to you? Yes 1 No

How can we help?