* @version 0.0.0
* @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
* @license GNU GPL 3.0 or any newer version
* @link http://www.shipsimu.org
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see .
*/
abstract class BaseTemplateEngine extends BaseFrameworkSystem {
// Load traits
use IoHandlerTrait;
// Exception codes for the template engine
const EXCEPTION_TEMPLATE_TYPE_IS_UNEXPECTED = 0x110;
const EXCEPTION_TEMPLATE_CONTAINS_INVALID_VAR = 0x111;
const EXCEPTION_INVALID_VIEW_HELPER = 0x112;
const EXCEPTION_VARIABLE_IS_MISSING = 0x113;
/**
* HTML template type
*/
private static $htmlTemplateType = 'invalid';
/**
* The local path name where all templates and sub folders for special
* templates are stored. We will internally determine the language plus
* "html" for web templates or "emails" for email templates
*/
private $templateBasePath = '';
/**
* Template type
*/
private $templateType = 'html';
/**
* The extension for web and email templates (not compiled templates)
*/
private $templateExtension = '.tpl';
/**
* The extension for code templates (not compiled templates)
*/
private $codeExtension = '.ctp';
/**
* Path relative to $templateBasePath and language code for compiled code-templates
*/
private $compileOutputPath = 'templates/_compiled/';
/**
* The path name for all templates
*/
private $genericBasePath = 'templates/';
/**
* The raw (maybe uncompiled) template
*/
private $rawTemplateData = '';
/**
* Template data with compiled-in variables
*/
private $compiledData = '';
/**
* The last loaded template's file instance (SplFileInfo)
*/
private $lastTemplate = NULL;
/**
* The variable stack for the templates
*/
private $varStack = [];
/**
* Loaded templates for recursive protection and detection
*/
private $loadedTemplates = [];
/**
* Compiled templates for recursive protection and detection
*/
private $compiledTemplates = [];
/**
* Loaded raw template data
*/
private $loadedRawData = NULL;
/**
* Raw templates which are linked in code templates
*/
private $rawTemplates = NULL;
/**
* A regular expression for variable=value pairs
*/
private $regExpVarValue = '/([\w_]+)(="([^"]*)"|=([\w_]+))?/';
/**
* A regular expression for filtering out code tags
*
* E.g.: {?template:variable=value;var2=value2;[...]?}
*/
private $regExpCodeTags = '/\{\?([a-z_]+)(:("[^"]+"|[^?}]+)+)?\?\}/';
/**
* A regular expression to find template comments like
*/
private $regExpComments = '//';
/**
* Loaded helpers
*/
private $helpers = [];
/**
* Current variable group
*/
private $currGroup = 'general';
/**
* All template groups except "general"
*/
private $variableGroups = [];
/**
* Code begin
*/
private $codeBegin = '';
/**
* Language support is enabled by default
*/
private $languageSupport = true;
/**
* Protected constructor
*
* @param $className Name of the class
* @return void
*/
protected function __construct (string $className) {
// Call parent constructor
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: className=%s - CONSTRUCTED!', $className));
parent::__construct($className);
// Init file I/O instance
$ioInstance = ObjectFactory::createObjectByConfiguredName('file_io_class');
// Set it
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: ioInstance=%s', $ioInstance->__toString()));
$this->setFileIoInstance($ioInstance);
// "Cache" config entry
self::$htmlTemplateType = FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('html_template_type');
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: self::htmlTemplateType=%s - EXIT!', self::$htmlTemplateType));
}
/**
* Search for a variable in the stack
*
* @param $variableName The variable we are looking for
* @param $variableGroup Optional variable group to look in
* @return $index false means not found, >=0 means found on a specific index
*/
private function getVariableIndex (string $variableName, string $variableGroup = NULL) {
// Replace all dashes to underscores to match variables with configuration entries
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: variableName=%s,variableGroup[%s]=%s - CALLED!', $variableName, gettype($variableGroup), $variableGroup));
$variableName = trim(StringUtils::convertDashesToUnderscores($variableName));
// First everything is not found
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: variableName=%s', $variableName));
$found = false;
// If the stack is NULL, use the current group
if (is_null($variableGroup)) {
// Use current group
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: this->currGroup=%s set as stack!', $this->currGroup));
$variableGroup = $this->currGroup;
}
// Is the group there?
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: variableGroup=%s', $variableGroup));
if ($this->isVarStackSet($variableGroup)) {
// Now search for it
foreach ($this->getVarStack($variableGroup) as $index => $currEntry) {
// Is the entry found?
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: index=%d,currGroup=%s,currEntry[name]=%s,variableName=%s', $index, $variableGroup, $currEntry['name'], $variableName));
if ($currEntry['name'] == $variableName) {
// Found!
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: index=%d - BREAK!', $index));
$found = $index;
break;
}
}
}
// Return the current position
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: found=%d - EXIT!', $found));
return $found;
}
/**
* Checks whether the given variable group is set
*
* @param $variableGroup Variable group to check
* @return $isSet Whether the given variable group is set
* @throws InvalidArgumentException If the variable name is left empty
*/
protected final function isVarStackSet (string $variableGroup) {
// Validate parameter
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: variableGroup=%s - CALLED!', $variableGroup));
if (empty($variableGroup)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Check it
$isset = isset($this->varStack[$variableGroup]);
// Return result
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: isset=%d - EXIT!', intval($isset)));
return $isset;
}
/**
* Getter for given variable group
*
* @param $variableGroup Variable group to check
* @return $varStack Found variable group
* @throws InvalidArgumentException If the variable name is left empty
*/
public final function getVarStack (string $variableGroup) {
// Validate parameter
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: variableGroup=%s - CALLED!', $variableGroup));
if (empty($variableGroup)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Return value
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: this->varStack[%s]()=%d - EXIT!', $variableGroup, count($this->varStack[$variableGroup])));
return $this->varStack[$variableGroup];
}
/**
* Setter for given variable group
*
* @param $variableGroup Variable group to check
* @param $varStack Variable stack to check
* @return void
* @throws InvalidArgumentException If the variable name is left empty
*/
protected final function setVarStack (string $variableGroup, array $varStack) {
// Validate parameter
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: variableGroup=%s,varStack()=%d - CALLED!', $variableGroup, count($varStack)));
if (empty($variableGroup)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Set var stack
$this->varStack[$variableGroup] = $varStack;
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* Return a content of a variable or null if not found
*
* @param $variableName The variable we are looking for
* @param $variableGroup Optional variable group to look in
* @return $content Content of the variable or null if not found
* @throws InvalidArgumentException If the variable name is left empty
*/
protected function readVariable (string $variableName, string $variableGroup = NULL) {
// Check parameters
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: variableName=%s,variableGroup[%s]=%s - CALLED!', $variableName, gettype($variableGroup), $variableGroup));
if (empty($variableName)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
} elseif (!is_null($variableGroup) && empty($variableGroup)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Replace all dashes to underscores to match variables with configuration entries
$variableName = trim(StringUtils::convertDashesToUnderscores($variableName));
// First everything is not found
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: variableName=%s', $variableName));
$content = NULL;
// If the stack is NULL, use the current group
if (is_null($variableGroup)) {
// Use current group
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: this->currGroup=%s set as stack!', $this->currGroup));
$variableGroup = $this->currGroup;
}
// Get variable index
$found = $this->getVariableIndex($variableName, $variableGroup);
// Is the variable found?
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: found[]=%s', gettype($found)));
if ($found !== false) {
// Read it
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->getVariableValue(%s,%s) ...', $variableGroup, $found));
$content = $this->getVariableValue($variableGroup, $found);
}
// Return the current position
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: content()=%d - EXIT!', strlen($content)));
return $content;
}
/**
* Add a variable to the stack
*
* @param $variableName Name of variable to add
* @param $value Value we want to store in the variable
* @return void
*/
private function addVariable (string $variableName, $value) {
// Set general variable group
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: variableName=%s,value[]=%s - CALLED!', $variableName, gettype($value)));
$this->setVariableGroup('general');
// Add it to the stack
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->addVariableGroup(%s,value[]=%s) ...', $variableName, gettype($value)));
$this->addGroupVariable($variableName, $value);
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* Returns all variables of current group or empty array
*
* @return $result Whether array of found variables or empty array
*/
private function readCurrentGroup () {
// Default is not found
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: CALLED!');
$result = [];
// Is the group there?
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: this->currGroup=%s', $this->currGroup));
if ($this->isVarStackSet($this->currGroup)) {
// Then use it
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->getVarStack(%s) ...', $this->currGroup));
$result = $this->getVarStack($this->currGroup);
}
// Return result
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: result()=%d - EXIT!', count($result)));
return $result;
}
/**
* Settter for variable group
*
* @param $groupName Name of variable group
* @param $add Whether add this group
* @return void
* @throws InvalidArgumentException If the variable name is left empty
*/
public function setVariableGroup (string $groupName, bool $add = true) {
// Check parameter
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: groupName=%s,add=%d - CALLED!', $groupName, intval($add)));
if (empty($groupName)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "groupName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Set group name
$this->currGroup = $groupName;
// Skip group 'general'
if (($groupName != 'general') && ($add === true)) {
// Mark as 'OK'
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: Marking groupName=%s as OK ...', $groupdName));
$this->variableGroups[$groupName] = 'OK';
}
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* Adds a variable to current group
*
* @param $variableName Variable to set
* @param $value Value to store in variable
* @return void
* @throws InvalidArgumentException If the variable name is left empty
*/
public function addGroupVariable (string $variableName, $value) {
// Check parameter
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: variableName=%s,value[]=%s - CALLED!', $variableName, gettype($value)));
if (empty($variableName)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
} elseif (is_object($value) || is_resource($value)) {
// Throw an exception
throw new InvalidArgumentException(sprintf('value[]=%s is not supported', gettype($value)), FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Replace all dashes to underscores to match variables with configuration entries
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking StringUtils::convertDashesToUnderscores(%s) ...', $variableName));
$variableName = trim(StringUtils::convertDashesToUnderscores($variableName));
// Get current variables in group
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: this->currGroup=%s,variableName=%s,value[]=%s', $this->currGroup, $variableName, gettype($value)));
$currVars = $this->readCurrentGroup();
// Append our variable
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: currVars()=%d - BEFORE!', count($currVars)));
array_push($currVars, $this->generateVariableArray($variableName, $value));
// Add it to the stack
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->setVarStack(%s,currVars()=%d) - AFTER!', $this->currGroup, count($currVars)));
$this->setVarStack($this->currGroup, $currVars);
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* Getter for variable value, throws a NoVariableException if the variable is not found
*
* @param $variableGroup Variable group to use
* @param $index Index in variable array
* @return $value Value to set
*/
private function getVariableValue (string $variableGroup, int $index) {
// Return it
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: variableGroup=%s,index[]=%d - CALLED!', $variableGroup, $index));
$value = $this->varStack[$variableGroup][$index]['value'];
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: value[]=%s - EXIT!', gettype($value)));
return $value;
}
/**
* Modify an entry on the stack
*
* @param $variableName The variable we are looking for
* @param $value The value we want to store in the variable
* @return void
*/
private function modifyVariable (string $variableName, $value) {
// Replace all dashes to underscores to match variables with configuration entries
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: variableName=%s,value[]=%s - CALLED!', $variableName, gettype($value)));
$variableName = trim(StringUtils::convertDashesToUnderscores($variableName));
// Get index for variable
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: this->getVariableIndex(%s) ...', $variableName));
$index = $this->getVariableIndex($variableName);
// Then modify it
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: this->setVariableValue(%s,%d,value[]=%s) ...', $this->currGroup, $index, gettype($value)));
$this->setVariableValue($this->currGroup, $index, $value);
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* Sets a variable value for given variable group and index
*
* @param $variableGroup Variable group to use
* @param $index Index in variable array
* @param $value Value to set
* @return void
*/
private function setVariableValue (string $variableGroup, int $index, $value) {
// Set variable
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: variableGroup=%s,index[]=%d,value[]=%s - CALLED!', $variableGroup, $index, gettype($value)));
$this->varStack[$variableGroup][$index]['value'] = $value;
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* Sets a variable within given group. This method does detect if the
* variable is already set. If so, the variable got modified, otherwise
* added.
*
* @param $variableGroup Variable group to use
* @param $variableName Variable to set
* @param $value Value to set
* @return void
* @throws InvalidArgumentException If the variable name is left empty
*/
protected function setVariable (string $variableGroup, string $variableName, $value) {
// Check parameters
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: variableGroup=%s,variableName=%s,value[]=%s - CALLED!', $variableGroup, $variableName, gettype($value)));
if (empty($variableGroup)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
} elseif (empty($variableName)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Replace all dashes to underscores to match variables with configuration entries
$variableName = trim(StringUtils::convertDashesToUnderscores($variableName));
// Get index for variable
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: this->getVariableIndex(%s) ...', $variableName));
$index = $this->getVariableIndex($variableName);
// Is the variable set?
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: index[]=%s', gettype($index)));
if ($index === false) {
// Is the stack there?
if (!isset($this->varStack[$variableGroup])) {
// Then initialize it here
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: Initializing this->varStack[%s] ...', $variableGroup));
$this->varStack[$variableGroup] = [];
}
// Not found, add it
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: Pushing variableGroup=%s,variableName=%s,value[]=%s ...', $variableGroup, $variableName, gettype($value)));
array_push($this->varStack[$variableGroup], $this->generateVariableArray($variableName, $value));
} else {
// Then modify it
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->setVariableValue(%s,%d,value[]=%s) ...', $this->currGroup, $index, gettype($value)));
$this->setVariableValue($this->currGroup, $index, $value);
}
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* "Generates" (better returns) an array for all variables for given
* variable/value pay.
*
* @param $variableName Variable to set
* @param $value Value to set
* @return $varData Variable data array
*/
private function generateVariableArray (string $variableName, $value) {
// Replace all dashes to underscores to match variables with configuration entries
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: variableName=%s,value[]=%s - CALLED!', $variableName, gettype($value)));
$variableName = trim(StringUtils::convertDashesToUnderscores($variableName));
// Generate the temporary array
$varData = [
'name' => $variableName,
'value' => $value
];
// And return it
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: varData()=%d - EXIT!', count($varData)));
return $varData;
}
/**
* Setter for template type. Only 'html', 'emails' and 'compiled' should
* be sent here
*
* @param $templateType The current template's type
* @return void
*/
protected final function setTemplateType (string $templateType) {
$this->templateType = $templateType;
}
/**
* Getter for template type
*
* @return $templateType The current template's type
*/
public final function getTemplateType () {
return $this->templateType;
}
/**
* Setter for the last loaded template's file instance
*
* @param $template The last loaded template
* @return void
*/
private final function setLastTemplate (SplFileInfo $fileInstance) {
$this->lastTemplate = $fileInstance;
}
/**
* Getter for the last loaded template's file instance
*
* @return $template The last loaded template
*/
private final function getLastTemplate () {
return $this->lastTemplate;
}
/**
* Setter for base path
*
* @param $templateBasePath The relative base path for all templates
* @return void
*/
protected final function setTemplateBasePath (string $templateBasePath) {
// And set it
$this->templateBasePath = $templateBasePath;
}
/**
* Getter for base path
*
* @return $templateBasePath The relative base path for all templates
*/
public final function getTemplateBasePath () {
// And set it
return $this->templateBasePath;
}
/**
* Getter for generic base path
*
* @return $templateBasePath The relative base path for all templates
*/
public final function getGenericBasePath () {
// And set it
return $this->genericBasePath;
}
/**
* Setter for template extension
*
* @param $templateExtension The file extension for all uncompiled
* templates
* @return void
*/
protected final function setRawTemplateExtension (string $templateExtension) {
// And set it
$this->templateExtension = $templateExtension;
}
/**
* Setter for code template extension
*
* @param $codeExtension The file extension for all uncompiled
* templates
* @return void
*/
protected final function setCodeTemplateExtension (string $codeExtension) {
// And set it
$this->codeExtension = $codeExtension;
}
/**
* Getter for template extension
*
* @return $templateExtension The file extension for all uncompiled
* templates
*/
public final function getRawTemplateExtension () {
// And set it
return $this->templateExtension;
}
/**
* Getter for code-template extension
*
* @return $codeExtension The file extension for all code-
* templates
*/
public final function getCodeTemplateExtension () {
// And set it
return $this->codeExtension;
}
/**
* Setter for path of compiled templates
*
* @param $compileOutputPath The local base path for all compiled
* templates
* @return void
*/
protected final function setCompileOutputPath (string $compileOutputPath) {
// And set it
$this->compileOutputPath = $compileOutputPath;
}
/**
* Unsets the given offset in the variable group
*
* @param $index Index to unset
* @param $variableGroup Variable group (default: currGroup)
* @return void
* @throws InvalidArgumentException If the variable name is left empty
* @throws BadMethodCallException If this method was called but combination of variableGroup/index isn't found
*/
protected final function unsetVariableStackOffset (int $index, string $variableGroup = NULL) {
// Check variables
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: index=%d,variableGroup[%s]=%s - CALLED!', $index, gettype($variableGroup), $variableGroup));
if ($index < 0) {
// Invalid index
throw new InvalidArgumentException(sprintf('index=%d is below zero', $index), FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
} elseif (!is_null($variableGroup) && empty($variableGroup)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Is the variable group not set?
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: variableGroup[]=%s', gettype($variableGroup)));
if (is_null($variableGroup)) {
// Then set it to current
$variableGroup = $this->currGroup;
}
// Is the entry there?
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: Checking variableGroup=%s,index=%d ...', $variableGroup, $index));
if (!isset($this->varStack[$variableGroup][$index])) {
// Abort here, we need fixing!
throw new BadMethodCallException(sprintf('variableGroup=%s,index=%d does not exist, but method was invoked', $variableGroup, $index), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
}
// Remove it
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: Unsetting variableGroup=%s,index=%d ...', $variableGroup, $index));
unset($this->varStack[$variableGroup][$index]);
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* Private setter for raw template data
*
* @param $rawTemplateData The raw data from the template
* @return void
*/
protected final function setRawTemplateData (string $rawTemplateData) {
// And store it in this class
$this->rawTemplateData = $rawTemplateData;
}
/**
* Getter for raw template data
*
* @return $rawTemplateData The raw data from the template
*/
public final function getRawTemplateData () {
return $this->rawTemplateData;
}
/**
* Private setter for compiled templates
*
* @param $compiledData Compiled template data
* @return void
*/
private final function setCompiledData (string $compiledData) {
// And store it in this class
$this->compiledData = $compiledData;
}
/**
* Getter for compiled templates, must be public for e.g. Mailer classes.
*
* @return $compiledData Compiled template data
*/
public final function getCompiledData () {
return $this->compiledData;
}
/**
* Private loader for all template types
*
* @param $templateName The template we shall load
* @param $extOther An other extension to use
* @return void
* @throws InvalidArgumentException If the variable name is left empty
* @throws FileNotFoundException If the template was not found
*/
protected function loadTemplate (string $templateName, string $extOther = '') {
// Check parameter
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: templateName=%s,extOther=%s - CALLED!', $templateName, $extOther));
if (empty($templateName)) {
// Throw IAE
throw new InvalidArgumentException('Parameter "templateName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Get extension for the template if empty
if (empty($extOther)) {
// None provided, so get the raw one
$ext = $this->getRawTemplateExtension();
} else {
// Then use it!
$ext = $extOther;
}
/*
* Construct the FQFN for the template without language as language is
* now entirely done by php_intl. These old thing with language-based
* template paths comes from an older time.
*/
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: ext=%s', $ext));
$fileInstance = new SplFileInfo(sprintf('%s%s%s%s%s%s',
$this->getTemplateBasePath(),
$this->getGenericBasePath(),
$this->getTemplateType(),
DIRECTORY_SEPARATOR,
(string) $templateName,
$ext
));
// First try this
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: fileInstance=%s', $fileInstance->__toString()));
try {
// Load the raw template data
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->loadRawTemplateData(%s) ...', $fileInstance->__toString()));
$this->loadRawTemplateData($fileInstance);
} catch (FileNotFoundException $e) {
// If we shall load a code-template we need to switch the file extension
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: this->templateType=%s,self::htmlTemplateType=%s,extOther=%s', $this->getTemplateType(), self::$htmlTemplateType, $extOther));
if (($this->getTemplateType() != self::$htmlTemplateType) && (empty($extOther))) {
// Switch over to the code-template extension and try it again
$ext = $this->getCodeTemplateExtension();
// Try it again...
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->loadTemplate(%s,%s) ...', $templateName, $ex));
$this->loadTemplate($templateName, $ext);
} else {
// Throw it again
throw new FileNotFoundException($fileInstance, self::EXCEPTION_FILE_NOT_FOUND);
}
}
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* A private loader for raw template names
*
* @param $fileInstance An instance of a SplFileInfo class
* @return void
*/
private function loadRawTemplateData (SplFileInfo $fileInstance) {
// Load the raw template
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: fileInstance=%s - CALLED!', $fileInstance->__toString()));
$rawTemplateData = $this->getFileIoInstance()->loadFileContents($fileInstance);
// Store the template's contents into this class
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->setRawTemplateData(%d) ...', strlen($rawTemplateData)));
$this->setRawTemplateData($rawTemplateData);
// Remember the template's file instance
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->setLastTemplate(%s) ...', $fileInstance->__toString()));
$this->setLastTemplate($fileInstance);
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* Try to assign an extracted template variable as a "content" or 'config'
* variable.
*
* @param $variableName The variable's name (shall be content or config)
* by default
* @param $configKey Possible configuration key
* @return void
*/
private function assignTemplateVariable (string $variableName, string $configKey = '') {
// Replace all dashes to underscores to match variables with configuration entries
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: variableName=%s,configKey=%s - CALLED!', $variableName, $configKey));
$variableName = trim(StringUtils::convertDashesToUnderscores($variableName));
// Is it not a config variable?
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: variableName=%s', $variableName));
if ($variableName != 'config') {
// Regular template variables
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->assignVariable(%s,"") ...', $variableName));
$this->assignVariable($variableName, '');
} else {
// Configuration variables
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->assignConfigVariable(%s,"") ...', $configKey));
$this->assignConfigVariable($configKey);
}
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* Extract variables from a given raw data stream
*
* @param $rawData The raw template data we shall analyze
* @return void
*/
private function extractVariablesFromRawData (string $rawData) {
// Search for variables
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: rawData(%d)=%s - CALLED!', strlen($rawData), $rawData));
preg_match_all('/\$(\w+)(\[(\w+)\])?/', $rawData, $variableMatches);
// Did we find some variables?
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: variableMatches[]=%s', gettype($variableMatches)));
if ((is_array($variableMatches)) && (count($variableMatches) == 4) && (count($variableMatches[0]) > 0)) {
// Initialize all missing variables
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: variableMatches()=%d', count($variableMatches)));
foreach ($variableMatches[3] as $key => $var) {
// Variable name
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: key=%s,var=%s', $key, $var));
$variableName = $variableMatches[1][$key];
// Workarround: Do not assign empty variables
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: variableName=%s', $variableName));
if (!empty($var)) {
// Try to assign it, empty strings are being ignored
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->assignTemplateVariable(%s,%s) ...', $variableName, $var));
$this->assignTemplateVariable($variableName, $var);
}
}
}
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* Main analysis of the loaded template
*
* @param $templateMatches Found template place-holders, see below
* @return void
*
*---------------------------------
* Structure of $templateMatches:
*---------------------------------
* [0] => Array - An array with all full matches
* [1] => Array - An array with left part (before the ':') of a match
* [2] => Array - An array with right part of a match including ':'
* [3] => Array - An array with right part of a match excluding ':'
*/
private function analyzeTemplate (array $templateMatches) {
// Backup raw template data
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: templateMatches()=%d', count($templateMatches)));
$backup = $this->getRawTemplateData();
// Initialize some arrays
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: backup[%s]()=%d,this->loadedRawData[]=%s', gettype($backup), strlen($backup), gettype($this->loadedRawData)));
if (is_null($this->loadedRawData)) {
// Initialize both
$this->loadedRawData = [];
$this->rawTemplates = [];
}
// Load all requested templates
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: templateMatches[1]()=%d', count($templateMatches[1])));
foreach ($templateMatches[1] as $template) {
// Load and compile only templates which we have not yet loaded
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: template=%s', $template));
// RECURSIVE PROTECTION! BE CAREFUL HERE!
if ((!isset($this->loadedRawData[$template])) && (!in_array($template, $this->loadedTemplates))) {
// Template not found, but maybe variable assigned?
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-TEMPLATE: template=%s not loaded yet', $template));
if ($this->getVariableIndex($template) !== false) {
// Use that content here
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-TEMPLATE: Assigning this->loadedTemplateData[%s] from variable template=%s ...', $template, $template));
$this->loadedRawData[$template] = $this->readVariable($template);
// Recursive protection:
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-TEMPLATE: Marking template=%s as loaded ...', $template));
array_push($this->loadedTemplates, $template);
} else {
// Then try to search for code-templates
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: template=%s is maybe name of code template?', $template));
try {
// Load the code template ...
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->loadCodeTemplate(%s) ...', $template));
$this->loadCodeTemplate($template);
// ... and remember it's contents
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-TEMPLATE: Setting this->loadedRawData[%s] from this->rawTemplateData ...', $template));
$this->loadedRawData[$template] = $this->getRawTemplateData();
// Remember this template for recursion detection
// RECURSIVE PROTECTION!
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-TEMPLATE: Marking template=%s as loaded ...', $template));
array_push($this->loadedTemplates, $template);
} catch (FileNotFoundException $e) {
// Even this is not done... :/
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-TEMPLATE: Marking template=%s as loaded ...', $template));
array_push($this->rawTemplates, $template);
}
}
}
}
// Restore the raw template data
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->setRawTemplateData(backup()=%d) ...', strlen($backup)));
$this->setRawTemplateData($backup);
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* Compile a given raw template code and remember it for later usage
*
* @param $code The raw template code
* @param $template The template's name
* @return void
*/
private function compileCode (string $code, string $template) {
// Is this template already compiled?
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: code=%s,template=%s - CALLED!', $code, $template));
if (in_array($template, $this->compiledTemplates)) {
// Abort here...
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Found template=%s in this->compiledTemplates - EXIT!', $template));
return;
}
// Remember this template being compiled
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: Adding template=%s to this->compiledTemplates ...', $template));
array_push($this->compiledTemplates, $template);
// Compile the loaded code in five steps:
//
// 1. Backup current template data
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: this->compiledTemplates()=%d', count($this->compiledTemplates)));
$backup = $this->getRawTemplateData();
// 2. Set the current template's raw data as the new content
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->setRawTemplateData(code()=%d) ... - backup[%s]()=%d', strlen($code), gettype($backup), strlen($backup)));
$this->setRawTemplateData($code);
// 3. Compile the template data
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: Invoking this->compileTemplate() ...');
$this->compileTemplate();
// 4. Remember it's contents
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-TEMPLATE: Setting this->loadedRawData[%s] from this->rawTemplateData ...', $template));
$this->loadedRawData[$template] = $this->getRawTemplateData();
// 5. Restore the previous raw content from backup variable
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: Invoking this->setRawTemplateData(backup()=%d) ...', strlen($backup)));
$this->setRawTemplateData($backup);
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* Insert all given and loaded templates by running through all loaded
* codes and searching for their place-holder in the main template
*
* @param $templateMatches See method analyzeTemplate()
* @return void
*/
private function insertAllTemplates (array $templateMatches) {
// Run through all loaded codes
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('BASE-TEMPLATE: templateMatches()=%d', count($templateMatches)));
foreach ($this->loadedRawData as $template => $code) {
// Search for the template
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: template=%s,code()=%d', $template, strlen($code)));
$foundIndex = array_search($template, $templateMatches[1]);
// Lookup the matching template replacement
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: foundIndex[%s]=d', gettype($foundIndex), $foundIndex));
if (($foundIndex !== false) && (isset($templateMatches[0][$foundIndex]))) {
// Get the current raw template
$rawData = $this->getRawTemplateData();
// Replace the space holder with the template code
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: rawData()=%s - BEFORE!', strlen($rawData)));
$rawData = str_replace($templateMatches[0][$foundIndex], $code, $rawData);
// Set the new raw data
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('BASE-TEMPLATE: rawData()=%s - AFTER!', strlen($rawData)));
$this->setRawTemplateData($rawData);
}
}
// Trace message
/* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('BASE-TEMPLATE: EXIT!');
}
/**
* Load all extra raw templates
*
* @return void
*/
private function loadExtraRawTemplates () {
// Are there some raw templates we need to load?
if (count($this->rawTemplates) > 0) {
// Try to load all raw templates
foreach ($this->rawTemplates as $key => $template) {
try {
// Load the template
$this->loadHtmlTemplate($template);
// Remember it's contents
$this->rawTemplates[$template] = $this->getRawTemplateData();
// Remove it from the loader list
unset($this->rawTemplates[$key]);
// Remember this template for recursion detection
// RECURSIVE PROTECTION!
array_push($this->loadedTemplates, $template);
} catch (FileNotFoundException $e) {
// This template was never found. We silently ignore it
unset($this->rawTemplates[$key]);
}
}
}
}
/**
* Assign all found template variables
*
* @param $varMatches An array full of variable/value pairs.
* @return void
* @todo Unfinished work or don't die here.
*/
private function assignAllVariables (array $varMatches) {
// Search for all variables
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:varMatches()=' . count($varMatches));
foreach ($varMatches[1] as $key => $var) {
// Replace all dashes to underscores to match variables with configuration entries
$var = trim(StringUtils::convertDashesToUnderscores($var));
// Debug message
self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:key=' . $key . ',var=' . $var);
// Detect leading equals
if (substr($varMatches[2][$key], 0, 1) == '=') {
// Remove and cast it
$varMatches[2][$key] = (string) substr($varMatches[2][$key], 1);
}
// Do we have some quotes left and right side? Then it is free text
if ((substr($varMatches[2][$key], 0, 1) == '"') && (substr($varMatches[2][$key], -1, 1) == '"')) {
// Free string detected! Which we can assign directly
$this->assignVariable($var, $varMatches[3][$key]);
} elseif (!empty($varMatches[2][$key])) {
// @TODO Non-string found so we need some deeper analysis...
ApplicationEntryPoint::exitApplication('Deeper analysis not yet implemented!');
}
}
}
/**
* Compiles all loaded raw templates
*
* @param $templateMatches See method analyzeTemplate() for details
* @return void
*/
private function compileRawTemplateData (array $templateMatches) {
// Are some code-templates found which we need to compile?
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:loadedRawData()= ' .count($this->loadedRawData));
if (count($this->loadedRawData) > 0) {
// Then compile all!
foreach ($this->loadedRawData as $template => $code) {
// Debug message
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:template=' . $template . ',code(' . strlen($code) . ')=' . $code);
// Is this template already compiled?
if (in_array($template, $this->compiledTemplates)) {
// Then skip it
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE: Template ' . $template . ' already compiled. SKIPPED!');
continue;
}
// Search for the template
$foundIndex = array_search($template, $templateMatches[1]);
// Lookup the matching variable data
if (($foundIndex !== false) && (isset($templateMatches[3][$foundIndex]))) {
// Split it up with another reg. exp. into variable=value pairs
preg_match_all($this->regExpVarValue, $templateMatches[3][$foundIndex], $varMatches);
//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:varMatches=' . print_r($varMatches, true));
// Assign all variables
$this->assignAllVariables($varMatches);
}
// Compile the loaded template
$this->compileCode($code, $template);
}
// Insert all templates
$this->insertAllTemplates($templateMatches);
}
}
/**
* Inserts all raw templates into their respective variables
*
* @return void
*/
private function insertRawTemplates () {
// Load all templates
foreach ($this->rawTemplates as $template => $content) {
// Set the template as a variable with the content
$this->assignVariable($template, $content);
}
}
/**
* Finalizes the compilation of all template variables
*
* @return void
*/
private function finalizeVariableCompilation () {
// Get the content
$content = $this->getRawTemplateData();
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE: content before=' . strlen($content) . ' (' . md5($content) . ')');
// Walk through all variables
foreach ($this->getVarStack('general') as $currEntry) {
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE: name=' . $currEntry['name'] . ', value=
' . htmlentities($currEntry['value']) . '
');
// Replace all [$var] or {?$var?} with the content
// @TODO Old behaviour, will become obsolete!
$content = str_replace('$content[' . $currEntry['name'] . ']', $currEntry['value'], $content);
// @TODO Yet another old way
$content = str_replace('[' . $currEntry['name'] . ']', $currEntry['value'], $content);
// The new behaviour
$content = str_replace('{?' . $currEntry['name'] . '?}', $currEntry['value'], $content);
}
// Set the content back
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE: content after=' . strlen($content) . ' (' . md5($content) . ')');
$this->setRawTemplateData($content);
}
/**
* Load a specified HTML template into the engine
*
* @param $template The web template we shall load which is located in
* 'html' by default
* @return void
* @throws InvalidArgumentException If the variable name is left empty
*/
public function loadHtmlTemplate (string $template) {
// Validate parameter
if (empty($template)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "template" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Set template type
$this->setTemplateType(self::$htmlTemplateType);
// Load the special template
$this->loadTemplate($template);
}
/**
* Assign (add) a given variable with a value
*
* @param $variableName The variable we are looking for
* @param $value The value we want to store in the variable
* @return void
* @throws InvalidArgumentException If the variable name is left empty
*/
public final function assignVariable (string $variableName, $value) {
// Validate parameter
if (empty($variableName)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Replace all dashes to underscores to match variables with configuration entries
$variableName = trim(StringUtils::convertDashesToUnderscores($variableName));
// First search for the variable if it was already added
$index = $this->getVariableIndex($variableName);
// Was it found?
if ($index === false) {
// Add it to the stack
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:ADD: ' . $variableName . '[' . gettype($value) . ']=' . $value);
$this->addVariable($variableName, $value);
} elseif (!empty($value)) {
// Modify the stack entry
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:MOD: ' . $variableName . '[' . gettype($value) . ']=' . $value);
$this->modifyVariable($variableName, $value);
}
}
/**
* Removes a given variable
*
* @param $variableName The variable we are looking for
* @param $variableGroup Name of variable group (default: 'general')
* @return void
* @throws InvalidArgumentException If the variable name is left empty
*/
public final function removeVariable (string $variableName, string $variableGroup = 'general') {
// Validate parameter
if (empty($variableName)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
} elseif (empty($variableGroup)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableGroup" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// First search for the variable if it was already added
$index = $this->getVariableIndex($variableName, $variableGroup);
// Was it found?
if ($index !== false) {
// Remove this variable
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:UNSET: variableGroup=' . $variableGroup . ',variableName=' . $variableName . ',index=' . $index);
$this->unsetVariableStackOffset($index, $variableGroup);
}
}
/**
* Assigns the last loaded raw template content with a given variable
*
* @param $templateName Name of the template we want to assign
* @param $variableName Name of the variable we want to assign
* @return void
* @throws InvalidArgumentException If the variable name is left empty
*/
public function assignTemplateWithVariable (string $templateName, string $variableName) {
// Validate parameter
if (empty($templateName)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "templateName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
} elseif (empty($variableName)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Get the content from last loaded raw template
$content = $this->getRawTemplateData();
// Assign the variable
$this->assignVariable($variableName, $content);
// Purge raw content
$this->setRawTemplateData('');
}
/**
* Assign a given congfiguration variable with a value
*
* @param $variableName The configuration variable we want to assign
* @return void
* @throws InvalidArgumentException If the variable name is left empty
*/
public function assignConfigVariable (string $variableName) {
// Validate parameter
if (empty($variableName)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "variableName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Replace all dashes to underscores to match variables with configuration entries
$variableName = trim(StringUtils::convertDashesToUnderscores($variableName));
// Sweet and simple...
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE: variableName=' . $variableName . ',getConfigEntry()=' . FrameworkBootstrap::getConfigurationInstance()->getConfigEntry($variableName));
$this->assignVariable($variableName, FrameworkBootstrap::getConfigurationInstance()->getConfigEntry($variableName));
}
/**
* Assigns a lot variables into the stack of currently loaded template.
* This method should only be used in very rare circumstances, e.g. when
* you have to copy a whole set of variables into the template engine.
* Before you use this method, please make sure you have considered all
* other possiblities.
*
* @param $variables An array with variables to be assigned
* @return void
*/
public function assignMultipleVariables (array $variables) {
// "Inject" all
foreach ($variables as $name => $value) {
// Set variable with name for 'config' group
$this->assignVariable($name, $value);
}
}
/**
* Assigns all the application data with template variables
*
* @return void
*/
public function assignApplicationData () {
// Get application instance
$applicationInstance = ApplicationHelper::getSelfInstance();
// Get long name and assign it
$this->assignVariable('app_full_name' , $applicationInstance->getAppName());
// Get short name and assign it
$this->assignVariable('app_short_name', $applicationInstance->getAppShortName());
// Get version number and assign it
$this->assignVariable('app_version' , $applicationInstance->getAppVersion());
// Assign extra application-depending data
$applicationInstance->assignExtraTemplateData($this);
}
/**
* Load a specified code template into the engine
*
* @param $template The code template we shall load which is
* located in 'code' by default
* @return void
* @throws InvalidArgumentException If the variable name is left empty
*/
public function loadCodeTemplate (string $template) {
// Validate parameter
if (empty($template)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "template" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Set template type
$this->setTemplateType(FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('code_' . FrameworkBootstrap::getRequestTypeFromSystem() . '_template_type'));
// Load the special template
$this->loadTemplate($template);
}
/**
* Load a specified email template into the engine
*
* @param $template The email template we shall load which is
* located in 'emails' by default
* @return void
* @throws InvalidArgumentException If the variable name is left empty
*/
public function loadEmailTemplate (string $template) {
// Validate parameter
if (empty($template)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "template" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Set template type
$this->setTemplateType(FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('email_template_type'));
// Load the special template
$this->loadTemplate($template);
}
/**
* Compiles configuration place-holders in all variables. This 'walks'
* through the variable group 'general'. It interprets all values from that
* variables as configuration entries after compiling them.
*
* @return void
*/
public final function compileConfigInVariables () {
// Do we have the stack?
if (!$this->isVarStackSet('general')) {
// Abort here silently
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE: Aborted, variable stack general not found!');
return;
}
// Iterate through all general variables
foreach ($this->getVarStack('general') as $index => $currVariable) {
// Compile the value
$value = $this->compileRawCode($this->readVariable($currVariable['name']), true);
// Debug message
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE: name=' . $currVariable['name'] . ',value=' . $value);
// Remove it from stack
$this->removeVariable($currVariable['name'], 'general');
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE: value='. $value . ',name=' . $currVariable['name'] . ',index=' . $index);
// Is it a configuration key?
if (FrameworkBootstrap::getConfigurationInstance()->isConfigurationEntrySet($value)) {
// The value itself is a configuration entry
$this->assignConfigVariable($value);
} else {
// Re-assign the value directly
$this->assignVariable($currVariable['name'], $value);
}
}
}
/**
* Compile all variables by inserting their respective values
*
* @return void
* @todo Make this code some nicer...
*/
public final function compileVariables () {
// Initialize the $content array
$validVar = FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('tpl_valid_var');
$dummy = [];
// Iterate through all general variables
foreach ($this->getVarStack('general') as $currVariable) {
// Transfer it's name/value combination to the $content array
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:' . $currVariable['name'] . '=' . htmlentities($currVariable['value']).'
');
$dummy[$currVariable['name']] = $currVariable['value'];
}
// Set the new variable (don't remove the second dollar!)
$$validVar = $dummy;
// Remove some variables
unset($index);
unset($currVariable);
// Run the compilation three times to get content from helper classes in
$cnt = 0;
while ($cnt < 3) {
// Finalize the compilation of template variables
$this->finalizeVariableCompilation();
// Prepare the eval() command for comiling the template
$eval = sprintf('$result = "%s";',
addslashes($this->getRawTemplateData())
);
// This loop does remove the backslashes (\) in PHP parameters
while (strpos($eval, $this->codeBegin) !== false) {
// Get left part before ""
$evalLeft = substr($eval, 0, strpos($eval, $this->codeBegin));
// Get all from right of ""
$evalRight = substr($eval, (strpos($eval, $this->codeBegin) + 5));
// Cut middle part out and remove escapes
$evalMiddle = trim(substr($evalRight, 0, strpos($evalRight, $this->codeEnd)));
$evalMiddle = stripslashes($evalMiddle);
// Remove the middle part from right one
$evalRight = substr($evalRight, (strpos($evalRight, $this->codeEnd) + 2));
// And put all together
$eval = sprintf('%s<%%php %s %%>%s', $evalLeft, $evalMiddle, $evalRight);
}
// Prepare PHP code for eval() command
$eval = str_replace(
'<%php', '";',
str_replace(
'%>',
"\n\$result .= \"",
$eval
)
);
// Run the constructed command. This will "compile" all variables in
eval($eval);
// Goes something wrong?
if ((!isset($result)) || (empty($result))) {
// Output eval command
self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('Failed eval() code: %s
', $this->markupCode($eval, true)), true);
// Output backtrace here
$this->debugBackTrace();
}
// Set raw template data
$this->setRawTemplateData($result);
$cnt++;
}
// Final variable assignment
$this->finalizeVariableCompilation();
// Set the new content
$this->setCompiledData($this->getRawTemplateData());
}
/**
* Compile all required templates into the current loaded one
*
* @return void
* @throws UnexpectedTemplateTypeException If the template type is
* not "code"
* @throws InvalidArrayCountException If an unexpected array
* count has been found
*/
public function compileTemplate () {
// Get code type to make things shorter
$codeType = FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('code_' . FrameworkBootstrap::getRequestTypeFromSystem() . '_template_type');
// We will only work with template type "code" from configuration
if (substr($this->getTemplateType(), 0, strlen($codeType)) != $codeType) {
// Abort here
throw new UnexpectedTemplateTypeException(array($this, $this->getTemplateType(), FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('code_' . FrameworkBootstrap::getRequestTypeFromSystem() . '_template_type')), self::EXCEPTION_TEMPLATE_TYPE_IS_UNEXPECTED);
}
// Get the raw data.
$rawData = $this->getRawTemplateData();
// Remove double spaces and trim leading/trailing spaces
$rawData = trim(str_replace(' ', ' ', $rawData));
// Search for raw variables
$this->extractVariablesFromRawData($rawData);
// Search for code-tags which are {? ?}
preg_match_all($this->regExpCodeTags, $rawData, $templateMatches);
// Debug message
//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:templateMatches=' . print_r($templateMatches , true));
// Analyze the matches array
if ((is_array($templateMatches)) && (count($templateMatches) == 4) && (count($templateMatches[0]) > 0)) {
// Entries are found:
//
// The main analysis
$this->analyzeTemplate($templateMatches);
// Compile raw template data
$this->compileRawTemplateData($templateMatches);
// Are there some raw templates left for loading?
$this->loadExtraRawTemplates();
// Are some raw templates found and loaded?
if (count($this->rawTemplates) > 0) {
// Insert all raw templates
$this->insertRawTemplates();
// Remove the raw template content as well
$this->setRawTemplateData('');
}
}
}
/**
* Loads a given view helper (by name)
*
* @param $helperName The helper's name
* @return void
* @throws InvalidArgumentException If the variable name is left empty
*/
protected function loadViewHelper (string $helperName) {
// Validate parameter
if (empty($helperName)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "helperName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Is this view helper loaded?
if (!isset($this->helpers[$helperName])) {
// Create a class name
$className = StringUtils::convertToClassName($helperName) . 'ViewHelper';
// Generate new instance
$this->helpers[$helperName] = ObjectFactory::createObjectByName($className);
}
// Return the requested instance
return $this->helpers[$helperName];
}
/**
* Transfers the content of this template engine to a given response instance
*
* @param $responseInstance An instance of a Responseable class
* @return void
*/
public function transferToResponse (Responseable $responseInstance) {
// Get the content and set it in response class
$responseInstance->writeToBody($this->getCompiledData());
}
/**
* "Compiles" a variable by replacing {?var?} with it's content
*
* @param $rawCode Raw code to compile
* @param $setMatchAsCode Sets $match if readVariable() returns empty result
* @return $rawCode Compile code with inserted variable value
* @throws InvalidArgumentException If the variable name is left empty
*/
public function compileRawCode (string $rawCode, bool $setMatchAsCode = false) {
// Validate parameter
if (empty($rawCode)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "rawCode" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Find the variables
//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:rawCode=' . htmlentities($rawCode) . '
');
preg_match_all($this->regExpVarValue, $rawCode, $varMatches);
// Compile all variables
//* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:' . print_r($varMatches, true) . '
');
foreach ($varMatches[0] as $match) {
// Add variable tags around it
$varCode = '{?' . $match . '?}';
// Debug message
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:varCode=' . $varCode);
// Is the variable found in code? (safes some calls)
if (strpos($rawCode, $varCode) !== false) {
// Debug message
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE: match=' . $match . ',rawCode[' . gettype($rawCode) . ']=' . $rawCode);
// Use $match as new value or $value from read variable?
if ($setMatchAsCode === true) {
// Insert match
$rawCode = str_replace($varCode, $match, $rawCode);
} else {
// Read the variable
$value = $this->readVariable($match);
// Insert value
$rawCode = str_replace($varCode, $value, $rawCode);
}
}
}
// Return the compiled data
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE:rawCode=' . htmlentities($rawCode) . '
');
return $rawCode;
}
/**
* Getter for variable group array
*
* @return $variableGroups All variable groups
*/
public final function getVariableGroups () {
return $this->variableGroups;
}
/**
* Renames a variable in code and in stack
*
* @param $oldName Old name of variable
* @param $newName New name of variable
* @return void
* @throws InvalidArgumentException If the variable name is left empty
*/
public function renameVariable (string $oldName, string $newName) {
// Validate parameter
//* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-TEMPLATE: oldName=' . $oldName . ', newName=' . $newName);
if (empty($oldName)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "oldName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
} elseif (empty($newName)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "newName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// Get raw template code
$rawData = $this->getRawTemplateData();
// Replace it
$rawData = str_replace($oldName, $newName, $rawData);
// Set the code back
$this->setRawTemplateData($rawData);
}
/**
* Enables or disables language support
*
* @param $languageSupport New language support setting
* @return void
*/
public final function enableLanguageSupport (bool $languageSupport = true) {
$this->languageSupport = $languageSupport;
}
/**
* Checks whether language support is enabled
*
* @return $languageSupport Whether language support is enabled or disabled
*/
public final function isLanguageSupportEnabled () {
return $this->languageSupport;
}
/**
* Removes all commentd, tabs and new-line characters to compact the content
*
* @param $uncompactedContent The uncompacted content
* @return $compactedContent The compacted content
*/
public function compactContent (string $uncompactedContent) {
// Validate parameter
if (empty($uncompactedContent)) {
// Throw an exception
throw new InvalidArgumentException('Parameter "uncompactedContent" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
}
// First, remove all tab/new-line/revert characters
$compactedContent = str_replace(chr(9), '', str_replace(chr(10), '', str_replace(chr(13), '', $uncompactedContent)));
// Then regex all comments like away
preg_match_all($this->regExpComments, $compactedContent, $matches);
// Do we have entries?
if (isset($matches[0][0])) {
// Remove all
foreach ($matches[0] as $match) {
// Remove the match
$compactedContent = str_replace($match, '', $compactedContent);
}
}
// Set the content again
$this->setRawTemplateData($compactedContent);
// Return compacted content
return $compactedContent;
}
}