Template Execution Context
In essence, configuration templates are PHP files which, when executed, output web server configuration files. The templates are executed in the environment where the specific variables $VAR and $OPT are available.
$VAR is an object containing the data model which should be applied to a template. The variable contains an essential set of parameters defining the content of web server configuration. The detailed structure of the array is presented in the Appendix C.
The most important function is IncludeTemplate() which is part of the $VAR array. The function allows including templates one into another, and it is defined as
IncludeTemplate($templateName, $OPT, $metainfo)where
-
$templateName- string denoting name of included template. Required -
$OPT- an associative array which passes values to a template. Optional -
$metainfo- an associative array which defines certain aliases in the template context. Optional
The basic function usage is as follows:
<span class="prefgrey">## source: default/server.php</span>
<?php echo $VAR->includeTemplate('server/tomcat.php') ?>
A text generated by the included template (server/tomcat.php) will be included in the configuration file.
In cases when the text generated by an included template should depend on the context, for example, when iterating over a set of values, it is possible to pass additional parameters to the template.
<span class="prefgrey"> ## source: default/server.php</span>
<?php echo $VAR->includeTemplate('service/php.php', array(
'enabled' => false,
)) ?>Here, we included the service/php.php template and passed the value 'enabled' => false to it. In the template being included the passed value is available in the variable $OPT:
<span class="prefgrey">## source: service/php.php</span>
<?php
if ($OPT['enabled']) { <span class="prefgrey">// it is required to detect 'enabled'</span>
echo "php_admin_flag engine on\n";
if (!array_key_exists('safe_mode', $OPT) || $OPT['safe_mode']) { <span class="prefgrey">// optional parameter 'safe_mode'</span>
echo "php_admin_flag safe_mode on\n";
} else {
echo "php_admin_flag safe_mode off\n";
}
if(array_key_exists('dir', $OPT) && $OPT['dir']) { <span class="prefgrey">// optional parameter 'dir'</span>
echo "php_admin_value open_basedir {$OPT['dir']}:/tmp\n";
}
} else {
echo "php_admin_flag engine off\n";
}
?>The code in this sample will generate two different blocks of text depending on which value of the 'enabled' parameter is passed.
Note that $VAR, which contains the data model, can be used in templates being included as well. Some values of $VAR are defined using the content of $metainfo. For details on possible $metainfo content and how it affects a template context, refer to Appendix C. For example, by defining the subDomainId value in the $metainfo parameter, it is possible to set an exact subdomain model available at $VAR->subDomain in a template being included:
<span class="prefgrey">## source: default/domainVhost.php</span>
<?php
<span class="prefgrey">//going through all subdomains of current domain</span>
foreach ($VAR->domain->physicalHosting->subdomains as $subdomain) {
if ($subdomain->ssl) { <span class="prefgrey">//if SSL is enabled on a subdomain</span>
<span class="prefgrey">//include configuration for subdomain with enabled SSL</span>
echo $VAR->includeTemplate('domain/subDomainVirtualHost.php', array(
'ssl' => true, <span class="prefgrey">// passing $OPT['ssl'] = true</span>
), array(
'subDomainId' => $subdomain->id, /<span class="prefgrey">/ define target subdomain for which a configuration file is being built</span>
));
}
<span class="prefgrey">//include configuration for subdomain with disabled ssl</span>
echo $VAR->includeTemplate('domain/subDomainVirtualHost.php', array(
'ssl' => false,
), array(
'subDomainId' => $subdomain->id,
));
}
?><span class="prefgrey"> ## source: domain/subDomainVirtualHost.php</span>
ServerName "<?php echo $VAR->subDomain->asciiName ?>.<?php echo $VAR->domain->asciiName ?>:<?php echo $OPT['ssl'] ? $VAR->server->webserver->httpsPort : $VAR->server->webserver->httpPort ?>"