SnippetBank.Net: PHP - Simple Template Engine Part 2

In part 1, I explained how to develop a simple find and replace template engine which substituted placeholders in a template file with scalar values. In this tutorial, I will explain how to access object properties and array elements in the template.

If you haven't already done so, I would suggest reading Simple Template Engine Part 1, which explains the find and replace technique.

Part 2

The str_replace() function is used to replace a search string with a new string. It can't however replace a string with an object or an array because it doesn't know which object property value or array element you want to replace it with. In this case, the str_replace() function becomes useless. Fortunately there is an alternative, which is to use a regular expression to extract all placeholders from the template and examine the content in each placeholder.

The first thing we need to do is determine the syntax for our placeholder. In the previous article the syntax for placeholders was {@placeholder}. To use object properties and array indexes, we can modify the syntax to be {@placeholder.propertyName} or {@placeholder.arrayKey}. We need to keep in mind that object properties can contain other objects and the same applies to arrays, which can contain other arrays or objects. For example, the following placeholder {@user.address.postcode} is a valid placeholder which suggests that property "address" is an object and has a "postcode" property. This means that placeholders can contain any number of properties and arrays.

Now that the placeholder syntax has been defined, we need to extract all placeholders from the template. This can be done with a simple regular expression. Since we want to replace the placeholder with a value we can use the preg_replace_callback() function. Unlike the str_replace() function, this function will allow us to use a regular expression and a callback. Let's take a look at some code for a better understanding.

echo preg_replace_callback('/\{@[0-9a-zA-z.]+\}.*?/', function($match){
return "Some text";
},$template);

In the code sample above the preg_replace_callback() function accepts 3 arguments, a regular expression that can match a single placeholder, a callback function that is executed when a match is found and the template code. In order to replace the matched placeholder, the callback function must return the replacement string.

The next step, is to clean and extract tokens from the matched placeholder. The match in the example code will contain the curly braces and the @ symbol. These characters can be removed easily by using the substr() function. You can use a group in the regular expression to only capture the inner string of the placeholder syntax but in this case we can use the substr() function as mentioned to clean the placeholder.

Once the placeholder has been cleaned, the next step is to determine, if the placeholder contains any properties/array keyes. We do this by checking for the presence of the "." character. Checking for the "." character tells us that this placeholder will be replaced by a non scalar value. Either an object or an array. Let's take a look at the revised code from above.

echo preg_replace_callback('/\{@[0-9a-zA-z.]+\}.*?/', function($match) {
if (isset($match[0])) {
$placeHolder = substr($match[0], 2, -1);
if (strpos($placeHolder, '.') > -1) {
// Placeholder is an object or an array
} else {
// Placeholder is a simple string, do a lookup
if (isset($parameters[$placeHolder])) {
return $parameters[$placeHolder];
} else {
throw new Exception(sprintf("Property '%s' not found", $placeHolder));
}
}
}
} ,$template);

As you can see on line 4, the placeholder is being cleaned. Once cleaned, the next part of the code determines if the placeholder contains a ".", which tells us it is either an object or an array replacement and further processing is require. If it's a simple placeholder, then we simply lookup its value in an array collection as discussed in Simple Template Engine Part 1. Notice on line 14 an exception is thrown if the placeholder is not found in the collection.

The final step is to process placeholders that need to be replaced with either an object or an array. To do this, the placeholder string is split into tokens at every "." character resulting in a array. We can iterate over each token and check if the token exists in the $parameters collection. This is better explained with an example.

Consider the following placeholder {@user.first_name}. Once cleaned and tokenized, it will result in an array containing two elements: array(user, first_name);

Also consider the following user object placed in the $paramaters collection:

$user = new stdClass();
$user->first_name = 'John';
$emailTemplate->addParameter('user', $user);

By iterating over the tokens, we can check if the first token "user" exists in the $parameters collection. In this case the check will evaluate to true since a parameter with the name "user" has been added. Once validated, the value ($user object) will be inspected to determine the variable type using both the is_object() and is_array() functions. If the value is of type object, we can use the get_object_vars() function to extract all the properties from the object as an array. This array will then replace the $parameters collection temporarily and the loop will continue to the next token which is the "first_name" token. Since the $parameters collection has been temporarily replaced with an array containing all of the $user object properties, the "first_name" token will be checked against this collection and the type checking process will start again, however since the value for the "first_name" property is a scalar value ("John"), the check to determine if the "first_name" value is an object or an array will fail and in this case the value is assumed to be a scalar and will be returned. This is demonstrated in the code below.

$tmp = $parameters;
foreach ($tokens as $token) {
if (isset($tmp[$token])) {
$item = $tmp[$token];
if (is_object($item)) {
$tmp = get_object_vars($item);
} elseif (is_array($item)) {
$tmp = $item;
} elseif (is_scalar($item)) {
return $item;
}
} else {
throw new Exception(sprintf("Property or index '%s' not found", $token));
}
}

Using this approach you can iterate over any number of tokens, while dealing with both objects and arrays. The final code smaple below shows the revised template class from part 1, with a few usages.

<?php
class Template {
private $template;
private $parameters = array();
public function __construct($file = null) {
if ($file) {
$this->load($file);
}
}
public function load($file) {
if (file_exists($file)) {
$this->template = file_get_contents($file);
}
}
public function addParameter($key, $value) {
$this->parameters[$key] = $value;
}
public function render() {
echo preg_replace_callback('/\{@[0-9a-zA-z.]+\}.*?/', function($match) {
if (isset($match[0])) {
$placeHolder = substr($match[0], 2, -1);
if (strpos($placeHolder, '.') > -1) {
$tokens = explode('.', $placeHolder);
return $this->parse($tokens, $this->parameters);
} else {
if (isset($this->parameters[$placeHolder])) {
return $this->parameters[$placeHolder];
} else {
throw new Exception(sprintf( "Property '%s' not found", $placeHolder));
}
}
}
},$this->template);
}
private function parse($tokens, $tmp) {
foreach($tokens as $token) {
if (isset($tmp[$token])) {
$item = $tmp[$token];
if (is_object($item)) {
$tmp = get_object_vars($item);
} elseif (is_array($item)) {
$tmp = $item;
} elseif (is_scalar($item)) {
return $item;
}
} else {
throw new Exception(sprintf( "Property or index '%s' not found", $token));
}
}
}
}
// Usage.
$user1 = new stdClass();
$user1->first_name = 'John';
$user1->last_name = 'Smith';
$user2 = new stdClass();
$user2->first_name = 'Syed';
$user2->last_name = 'Hussain';
$users = array($user1, $user2);
// Load the template file.
$emailTemplate = new Template('template.txt');
// Assign placeholder variable.
$emailTemplate->addParameter('users', $users);
$emailTemplate->addParameter('message', 'Welcome to our new mailing list.');
// Render the template
echo $emailTemplate->render();
?>

Template.txt

<div>
<h1>Hi {@users.0.first_name} {@users.0.last_name},</h1>
<p>{@message}</p>
<p>
Kind regards,<br/>
{@users.1.first_name} {@users.1.last_name}
</p>
</div>

This brings us to the end of this tutorial. If you're thinking of developing your own template engine consider reading up on Lexers and Parsers.

PHP - Simple Template Engine Part 2

Part 2

No comments:

Post a Comment