root/MiniTemplator.class.php

<?php
/**
* File MiniTemplator.class.php
* @package MiniTemplator
*/

/**
* A compact template engine for HTML files.
*
* Requires PHP 4.0.4 or newer.
*
* <pre>
* Template syntax:
*
*   Variables:
*     ${VariableName}
*
*   Blocks:
*     &lt;!-- $BeginBlock BlockName --&gt;
*     ... block content ...
*     &lt;!-- $EndBlock BlockName --&gt;
*
*   Include a subtemplate:
*     &lt;!-- $Include RelativeFileName --&gt;
* </pre>
*
* <pre>
* General remarks:
*  - Variable names and block names are case-insensitive.
*  - The same variable may be used multiple times within a template.
*  - Blocks can be nested.
*  - Multiple blocks with the same name may occur within a template.
* </pre>
*
* <pre>
* Public methods:
*   readTemplateFromFile   - Reads the template from a file.
*   setTemplateString      - Assigns a new template string.
*   setVariable            - Sets a template variable.
*   setVariableEsc         - Sets a template variable to an escaped string value.
*   variableExists         - Checks whether a template variable exists.
*   addBlock               - Adds an instance of a template block.
*   blockExists            - Checks whether a block exists.
*   reset                  - Clears all variables and blocks.
*   generateOutput         - Generates the HTML page and writes it to the PHP output stream.
*   generateOutputToFile   - Generates the HTML page and writes it to a file.
*   generateOutputToString - Generates the HTML page and writes it to a string.
* </pre>
*
* Home page: {@link http://www.source-code.biz/MiniTemplator}<br>
* License: This module is released under the GNU/LGPL license ({@link http://www.gnu.org/licenses/lgpl.html}).<br>
* Copyright 2003: Christian d'Heureuse, Inventec Informatik AG, Switzerland. All rights reserved.<br>
* This product is provided "as is" without warranty of any kind.<br>
*
* Version history:<br>
* 2001-10-24 Christian d'Heureuse (chdh): VBasic version created.<br>
* 2002-01-26 Markus Angst: ported to PHP4.<br>
* 2003-04-07 chdh: changes to adjust to Java version.<br>
* 2003-07-08 chdh: Method variableExists added.
*   Method setVariable changed to trigger an error when the variable does not exist.<br>
* 2004-04-07 chdh: Parameter isOptional added to method setVariable.
*   Licensing changed from GPL to LGPL.<br>
* 2004-04-18 chdh: Method blockExists added.<br>
* 2004-10-28 chdh:<br>
*   Method setVariableEsc added.<br>
*   Multiple blocks with the same name may now occur within a template.<br>
*   No error ("unknown command") is generated any more, if a HTML comment starts with "${".<br>
* 2004-11-06 chdh:<br>
*   "$Include" command implemented.<br>
* 2004-11-20 chdh:<br>
*   "$Include" command changed so that the command text is not copied to the output file.<br>
*/

class MiniTemplator {

//--- public member variables ---------------------------------------------------------------------------------------

/**
* Base path for relative file names of subtemplates (for the $Include command).
* This path is prepended to the subtemplate file names. It must be set before
* readTemplateFromFile or setTemplateString.
* @access public
*/
var $subtemplateBasePath;

//--- private member variables --------------------------------------------------------------------------------------

/**#@+
* @access private
*/

var $maxNestingLevel = 50;            // maximum number of block nestings
var $maxInclTemplateSize = 1000000;   // maximum length of template string when including subtemplates
var $template;                        // Template file data
var $varTab;                          // variables table, array index is variable no
    // Fields:
    //  varName                       // variable name
    //  varValue                      // variable value
var $varTabCnt;                       // no of entries used in VarTab
var $varNameToNoMap;                  // maps variable names to variable numbers
var $varRefTab;                       // variable references table
    // Contains an entry for each variable reference in the template. Ordered by TemplatePos.
    // Fields:
    //  varNo                         // variable no
    //  tPosBegin                     // template position of begin of variable reference
    //  tPosEnd                       // template position of end of variable reference
    //  blockNo                       // block no of the (innermost) block that contains this variable reference
    //  blockVarNo                    // block variable no. Index into BlockInstTab.BlockVarTab
var $varRefTabCnt;                    // no of entries used in VarRefTab
var $blockTab;                        // Blocks table, array index is block no
    // Contains an entry for each block in the template. Ordered by TPosBegin.
    // Fields:
    //  blockName                     // block name
    //  nextWithSameName;             // block no of next block with same name or -1 (blocks are backward linked in relation to template position)
    //  tPosBegin                     // template position of begin of block
    //  tPosContentsBegin             // template pos of begin of block contents
    //  tPosContentsEnd               // template pos of end of block contents
    //  tPosEnd                       // template position of end of block
    //  nestingLevel                  // block nesting level
    //  parentBlockNo                 // block no of parent block
    //  definitionIsOpen              // true while $BeginBlock processed but no $EndBlock
    //  instances                     // number of instances of this block
    //  firstBlockInstNo              // block instance no of first instance of this block or -1
    //  lastBlockInstNo               // block instance no of last instance of this block or -1
    //  currBlockInstNo               // current block instance no, used during generation of output file
    //  blockVarCnt                   // no of variables in block
    //  blockVarNoToVarNoMap          // maps block variable numbers to variable numbers
    //  firstVarRefNo                 // variable reference no of first variable of this block or -1
var $blockTabCnt;                     // no of entries used in BlockTab
var $blockNameToNoMap;                // maps block names to block numbers
var $openBlocksTab;
    // During parsing, this table contains the block numbers of the open parent blocks (nested outer blocks).
    // Indexed by the block nesting level.
var $blockInstTab;                    // block instances table
    // This table contains an entry for each block instance that has been added.
    // Indexed by BlockInstNo.
    // Fields:
    //  blockNo                       // block number
    //  instanceLevel                 // instance level of this block
    //     InstanceLevel is an instance counter per block.
    //     (In contrast to blockInstNo, which is an instance counter over the instances of all blocks)
    //  parentInstLevel               // instance level of parent block
    //  nextBlockInstNo               // pointer to next instance of this block or -1
    //     Forward chain for instances of same block.
    //  blockVarTab                   // block instance variables
var $blockInstTabCnt;                 // no of entries used in BlockInstTab

var $currentNestingLevel;             // Current block nesting level during parsing.
var $templateValid;                   // true if a valid template is prepared
var $outputMode;                      // 0 = to PHP output stream, 1 = to file, 2 = to string
var $outputFileHandle;                // file handle during writing of output file
var $outputError;                     // true when an output error occurred
var $outputString;                    // string buffer for the generated HTML page

/**#@-*/

//--- constructor ---------------------------------------------------------------------------------------------------

/**
* Constructs a MiniTemplator object.
* @access public
*/
function MiniTemplator() {
   $this->templateValid = false; }

//--- template string handling --------------------------------------------------------------------------------------

/**
* Reads the template from a file.
* @param  string   $fileName  name of the file that contains the template.
* @return boolean  true on success, false on error.
* @access public
*/
function readTemplateFromFile ($fileName) {
   if (!$this->readFileIntoString($fileName,$s)) {
      $this->triggerError ("Error while reading template file " . $fileName . ".");
      return false; }
   if (!$this->setTemplateString($s)) return false;
   return true; }

/**
* Assigns a new template string.
* @param  string   $templateString  contents of the template file.
* @return boolean  true on success, false on error.
* @access public
*/
function setTemplateString ($templateString) {
   $this->templateValid = false;
   $this->template = $templateString;
   if (!$this->parseTemplate()) return false;
   $this->reset();
   $this->templateValid = true;
   return true; }

/**
* Loads the template string for a subtemplate (used for the $Include command).
* @return boolean  true on success, false on error.
* @access private
*/
function loadSubtemplate ($subtemplateName, &$s) {
   $subtemplateFileName = $this->combineFileSystemPath($this->subtemplateBasePath,$subtemplateName);
   if (!$this->readFileIntoString($subtemplateFileName,$s)) {
      $this->triggerError ("Error while reading subtemplate file " . $subtemplateFileName . ".");
      return false; }
   return true; }

//--- template parsing ----------------------------------------------------------------------------------------------

/**
* Parses the template.
* @return boolean  true on success, false on error.
* @access private
*/
function parseTemplate() {
   $this->initParsing();
   $this->beginMainBlock();
   if (!$this->parseTemplateCommands()) return false;
   $this->endMainBlock();
   if (!$this->checkBlockDefinitionsComplete()) return false;
   if (!$this->parseTemplateVariables()) return false;
   $this->associateVariablesWithBlocks();
   return true; }

/**
* @access private
*/
function initParsing() {
   $this->varTab = array();
   $this->varTabCnt = 0;
   $this->varNameToNoMap = array();
   $this->varRefTab = array();
   $this->varRefTabCnt = 0;
   $this->blockTab = array();
   $this->blockTabCnt = 0;
   $this->blockNameToNoMap = array();
   $this->openBlocksTab = array(); }

/**
* Registers the main block.
* The main block is an implicitly defined block that covers the whole template.
* @access private
*/
function beginMainBlock() {
   $blockNo = 0;
   $this->registerBlock('@@InternalMainBlock@@', $blockNo);
   $bte =& $this->blockTab[$blockNo];
   $bte['tPosBegin'] = 0;
   $bte['tPosContentsBegin'] = 0;
   $bte['nestingLevel'] = 0;
   $bte['parentBlockNo'] = -1;
   $bte['definitionIsOpen'] = true;
   $this->openBlocksTab[0] = $blockNo;
   $this->currentNestingLevel = 1; }

/**
* Completes the main block registration.
* @access private
*/
function endMainBlock() {
   $bte =& $this->blockTab[0];
   $bte['tPosContentsEnd'] = strlen($this->template);
   $bte['tPosEnd'] = strlen($this->template);
   $bte['definitionIsOpen'] = false;
   $this->currentNestingLevel -= 1; }

/**
* Parses commands within the template in the format "<!-- $command parameters -->".
* @return boolean  true on success, false on error.
* @access private
*/
function parseTemplateCommands() {
   $p = 0;
   while (true) {
      $p0 = strpos($this->template,'<!--',$p);
      if ($p0 === false) break;
      $p = strpos($this->template,'-->',$p0);
      if ($p === false) {
         $this->triggerError ("Invalid HTML comment in template at offset $p0.");
         return false; }
      $p += 3;
      $cmdL = substr($this->template,$p0+4,$p-$p0-7);
      if (!$this->processTemplateCommand($cmdL,$p0,$p,$resumeFromStart))
         return false;
      if ($resumeFromStart) $p = $p0; }
   return true; }

/**
* @return boolean  true on success, false on error.
* @access private
*/
function processTemplateCommand ($cmdL, $cmdTPosBegin, $cmdTPosEnd, &$resumeFromStart) {
   $resumeFromStart = false;
   $p = 0;
   $cmd = '';
   if (!$this->parseWord($cmdL,$p,$cmd)) return true;
   $parms = substr($cmdL,$p);
   switch (strtoupper($cmd)) {
      case '$BEGINBLOCK':
         if (!$this->processBeginBlockCmd($parms,$cmdTPosBegin,$cmdTPosEnd))
            return false;
         break;
      case '$ENDBLOCK':
         if (!$this->processEndBlockCmd($parms,$cmdTPosBegin,$cmdTPosEnd))
            return false;
         break;
      case '$INCLUDE':
         if (!$this->processincludeCmd($parms,$cmdTPosBegin,$cmdTPosEnd))
            return false;
         $resumeFromStart = true;
         break;
      default:
         if ($cmd{0} == '$' && !(strlen($cmd) >= 2 && $cmd{1} == '{')) {
            $this->triggerError ("Unknown command \"$cmd\" in template at offset $cmdTPosBegin.");
            return false; }}
    return true; }

/**
* Processes the $BeginBlock command.
* @return boolean  true on success, false on error.
* @access private
*/
function processBeginBlockCmd ($parms, $cmdTPosBegin, $cmdTPosEnd) {
   $p = 0;
   if (!$this->parseWord($parms,$p,$blockName)) {
      $this->triggerError ("Missing block name in \$BeginBlock command in template at offset $cmdTPosBegin.");
      return false; }
   if (trim(substr($parms,$p)) != '') {
      $this->triggerError ("Extra parameter in \$BeginBlock command in template at offset $cmdTPosBegin.");
      return false; }
   $this->registerBlock ($blockName, $blockNo);
   $btr =& $this->blockTab[$blockNo];
   $btr['tPosBegin'] = $cmdTPosBegin;
   $btr['tPosContentsBegin'] = $cmdTPosEnd;
   $btr['nestingLevel'] = $this->currentNestingLevel;
   $btr['parentBlockNo'] = $this->openBlocksTab[$this->currentNestingLevel-1];
   $this->openBlocksTab[$this->currentNestingLevel] = $blockNo;
   $this->currentNestingLevel += 1;
   if ($this->currentNestingLevel > $this->maxNestingLevel) {
      $trhis->triggerError ("Block nesting overflow in template at offset $cmdTPosBegin.");
      return false; }
   return true; }

/**
* Processes the $EndBlock command.
* @return boolean  true on success, false on error.
* @access private
*/
function processEndBlockCmd ($parms, $cmdTPosBegin, $cmdTPosEnd) {
   $p = 0;
   if (!$this->parseWord($parms,$p,$blockName)) {
      $this->triggerError ("Missing block name in \$EndBlock command in template at offset $cmdTPosBegin.");
      return false; }
   if (trim(substr($parms,$p)) != '') {
      $this->triggerError ("Extra parameter in \$EndBlock command in template at offset $cmdTPosBegin.");
      return false; }
   if (!$this->lookupBlockName($blockName,$blockNo)) {
      $this->triggerError ("Undefined block name \"$blockName\" in \$EndBlock command in template at offset $cmdTPosBegin.");
      return false; }
   $this->currentNestingLevel -= 1;
   $btr =& $this->blockTab[$blockNo];
   if (!$btr['definitionIsOpen']) {
      $this->triggerError ("Multiple \$EndBlock command for block \"$blockName\" in template at offset $cmdTPosBegin.");
      return false; }
   if ($btr['nestingLevel'] != $this->currentNestingLevel) {
      $this->triggerError ("Block nesting level mismatch at \$EndBlock command for block \"$blockName\" in template at offset $cmdTPosBegin.");
      return false; }
   $btr['tPosContentsEnd'] = $cmdTPosBegin;
   $btr['tPosEnd'] = $cmdTPosEnd;
   $btr['definitionIsOpen'] = false;
   return true; }

/**
* @access private
*/
function registerBlock($blockName, &$blockNo) {
   $blockNo = $this->blockTabCnt++;
   $btr =& $this->blockTab[$blockNo];
   $btr = array();
   $btr['blockName'] = $blockName;
   if (!$this->lookupBlockName($blockName,$btr['nextWithSameName']))
      $btr['nextWithSameName'] = -1;
   $btr['definitionIsOpen'] = true;
   $btr['instances'] = 0;
   $btr['firstBlockInstNo'] = -1;
   $btr['lastBlockInstNo'] = -1;
   $btr['blockVarCnt'] = 0;
   $btr['firstVarRefNo'] = -1;
   $btr['blockVarNoToVarNoMap'] = array();
   $this->blockNameToNoMap[strtoupper($blockName)] = $blockNo; }

/**
* Checks that all block definitions are closed.
* @return boolean  true on success, false on error.
* @access private
*/
function checkBlockDefinitionsComplete() {
   for ($blockNo=0; $blockNo < $this->blockTabCnt; $blockNo++) {
      $btr =& $this->blockTab[$blockNo];
      if ($btr['definitionIsOpen']) {
         $this->triggerError ("Missing \$EndBlock command in template for block " . $btr['blockName'] . ".");
         return false; }}
   if ($this->currentNestingLevel != 0) {
      $this->triggerError ("Block nesting level error at end of template.");
      return false; }
   return true; }

/**
* Processes the $Include command.
* @return boolean  true on success, false on error.
* @access private
*/
function processIncludeCmd ($parms, $cmdTPosBegin, $cmdTPosEnd) {
   $p = 0;
   if (!$this->parseWordOrQuotedString($parms,$p,$subtemplateName)) {
      $this->triggerError ("Missing or invalid subtemplate name in \$Include command in template at offset $cmdTPosBegin.");
      return false; }
   if (trim(substr($parms,$p)) != '') {
      $this->triggerError ("Extra parameter in \$include command in template at offset $cmdTPosBegin.");
      return false; }
   return $this->insertSubtemplate($subtemplateName,$cmdTPosBegin,$cmdTPosEnd); }

/**
* Processes the $Include command.
* @return boolean  true on success, false on error.
* @access private
*/
function insertSubtemplate ($subtemplateName, $tPos1, $tPos2) {
   if (strlen($this->template) > $this->maxInclTemplateSize) {
      $this->triggerError ("Subtemplate include aborted because the internal template string is longer than $this->maxInclTemplateSize characters.");
      return false; }
   if (!$this->loadSubtemplate($subtemplateName,$subtemplate)) return false;
   // (Copying the template to insert a subtemplate is a bit slow. In a future implementation of MiniTemplator,
   // a table could be used that contains references to the string fragments.)
   $this->template = substr($this->template,0,$tPos1) . $subtemplate . substr($this->template,$tPos2);
   return true; }

/**
* Parses variable references within the template in the format "${VarName}".
* @return boolean  true on success, false on error.
* @access private
*/
function parseTemplateVariables() {
   $p = 0;
   while (true) {
      $p = strpos($this->template, '${', $p);
      if ($p === false) break;
      $p0 = $p;
      $p = strpos($this->template, '}', $p);
      if ($p === false) {
         $this->triggerError ("Invalid variable reference in template at offset $p0.");
         return false; }
      $p += 1;
      $varName = trim(substr($this->template, $p0+2, $p-$p0-3));
      if (strlen($varName) == 0) {
         $this->triggerError ("Empty variable name in template at offset $p0.");
         return false; }
      $this->registerVariableReference ($varName, $p0, $p); }
   return true; }

/**
* @access private
*/
function registerVariableReference ($varName, $tPosBegin, $tPosEnd) {
   if (!$this->lookupVariableName($varName,$varNo))
      $this->registerVariable($varName,$varNo);
   $varRefNo = $this->varRefTabCnt++;
   $vrtr =& $this->varRefTab[$varRefNo];
   $vrtr = array();
   $vrtr['tPosBegin'] = $tPosBegin;
   $vrtr['tPosEnd'] = $tPosEnd;
   $vrtr['varNo'] = $varNo; }

/**
* @access private
*/
function registerVariable ($varName, &$varNo) {
   $varNo = $this->varTabCnt++;
   $vtr =& $this->varTab[$varNo];
   $vtr = array();
   $vtr['varName'] = $varName;
   $vtr['varValue'] = '';
   $this->varNameToNoMap[strtoupper($varName)] = $varNo; }

/**
* Associates variable references with blocks.
* @access private
*/
function associateVariablesWithBlocks() {
   $varRefNo = 0;
   $activeBlockNo = 0;
   $nextBlockNo = 1;
   while ($varRefNo < $this->varRefTabCnt) {
      $vrtr =& $this->varRefTab[$varRefNo];
      $varRefTPos = $vrtr['tPosBegin'];
      $varNo = $vrtr['varNo'];
      if ($varRefTPos >= $this->blockTab[$activeBlockNo]['tPosEnd']) {
         $activeBlockNo = $this->blockTab[$activeBlockNo]['parentBlockNo'];
         continue; }
      if ($nextBlockNo < $this->blockTabCnt) {
         if ($varRefTPos >= $this->blockTab[$nextBlockNo]['tPosBegin']) {
            $activeBlockNo = $nextBlockNo;
            $nextBlockNo += 1;
            continue; }}
      $btr =& $this->blockTab[$activeBlockNo];
      if ($varRefTPos < $btr['tPosBegin'])
         $this->programLogicError(1);
      $blockVarNo = $btr['blockVarCnt']++;
      $btr['blockVarNoToVarNoMap'][$blockVarNo] = $varNo;
      if ($btr['firstVarRefNo'] == -1)
         $btr['firstVarRefNo'] = $varRefNo;
      $vrtr['blockNo'] = $activeBlockNo;
      $vrtr['blockVarNo'] = $blockVarNo;
      $varRefNo += 1; }}

//--- build up (template variables and blocks) ----------------------------------------------------------------------

/**
* Clears all variables and blocks.
* This method can be used to produce another HTML page with the same
* template. It is faster than creating another MiniTemplator object,
* because the template does not have to be parsed again.
* All variable values are cleared and all added block instances are deleted.