ConLite/conlite/classes/class.cec_hook.php

423 Zeilen
15 KiB
PHP

<?php
/**
* Project:
* Contenido Content Management System
*
* Description:
* Includes CEC hook class
*
* Requirements:
* @con_php_req 5.0
*
*
* @package Contenido Backend classes
* @subpackage CEC
* @version 0.5
* @author Murat Purc <murat@purc.de>
* @copyright four for business AG <www.4fb.de>
* @license http://www.contenido.org/license/LIZENZ.txt
* @link http://www.4fb.de
* @link http://www.contenido.org
* @since file available since contenido release >= 4.8.8
*
* {@internal
* created 2008-08-28, Murat Purc, initial implementation, port from Advanced Mod Rewrite Plugin
* modified 2008-09-10, Murat Purc, bugfix: add further condition handling to prevent overwriting of arguments
* modified 2008-11-11, Andreas Lindner, when overwriting of arguments is prevented and break condition is set
* added anoption to return break condition value directly, otherwise the args would be returned, which is not
* desirable under all circumstances
* modified 2008-12-26, Murat Purc, bugfix: Not each registered chain function will get the same parameter
* modified 2009-12-26, Murat Purc, bugfix/redesign of CEC_Hook, see [#CON-256]
*
* }}
*
*/
/**
* Static CEC Hook class, provides some public methods to process registered chains
* at CEC (Contenido Extension Chainer).
*
* Usage:
* <code>
* // example of executing a cec without a parameter and return value
* CEC_Hook::execute('Contenido.Content.Somewhere');
*
* // example of executing a cec with a parameter but without a return value
* $param = 'some value';
* CEC_Hook::execute('Contenido.Content.Somewhere', $param);
*
* // example of executing a cec with multiple parameter but without a return value
* $param = array('foo' => $bar, 'foo2' => $bar2);
* $param = CEC_Hook::execute('Contenido.Content.Somewhere', $param);
*
*
* // example of executing a cec without a parameter but a return value (with predefined
* // default return value)
* CEC_Hook::setDefaultReturnValue('this is the default title');
* $title = CEC_Hook::executeAndReturn('Contenido.Content.CreateTitletag');
*
* // example of executing a cec with a parameter and a return value
* // (usually the modified version of passed parameter)
* $baseHref = $cfgClient[$client]['path']['htmlpath'];
* $newBaseHref = CEC_Hook::executeAndReturn('Contenido.Frontend.BaseHrefGeneration', $baseHref);
*
*
* // example of executing a cec with a break condition and default return value
* CEC_Hook::setBreakCondition(false, true); // break condition = "false", default return value = "true"
* $allow = CEC_Hook::executeWhileBreakCondition('Contenido.Frontend.AllowEdit', $lang, $idcat, $idart, $auth->auth['uid']);
* if ($allow == false) {
* die("You're not coming in!");
* }
*
* // another example of executing a cec with a break condition and default return value
* CEC_Hook::setBreakCondition(true, false); // break condition = "true", default return value = "false"
* $allow = CEC_Hook::executeWhileBreakCondition('Contenido.Frontend.CategoryAccess', $lang, $idcat, $auth->auth['uid']);
* if ($allow == false) {
* die("I said, you're not coming in!");
* }
* </code>
*
* @author Murat Purc <murat@purc.de>
* @package Contenido Backend classes
* @subpackage CEC
*/
class CEC_Hook {
/**
* Value to break the cec execution at a true result
* @deprecated see CEC_Hook::setConditions()
* @var int
*/
const BREAK_AT_TRUE = 'true';
/**
* Value to break the cec execution at a false result
* @deprecated see CEC_Hook::setConditions()
* @var int
*/
const BREAK_AT_FALSE = 'false';
/**
* Value to break the cec execution at a null result
* @deprecated see CEC_Hook::setConditions()
* @var int
*/
const BREAK_AT_NULL = 'null';
/**
* Flag to return the set break condition directly.
* @deprecated No more needed
* @var bool
*/
static private $_returnBreakConditionDirectly = false;
/**
* Flag to overwrite arguments.
* @deprecated No more needed
* @var bool
*/
static private $_overwriteArguments = true;
/**
* Temporaly stored break condition.
* @var int
*/
static private $_breakCondition = null;
/**
* Temporaly stored default return value of CEC functions
* @var mixed
*/
static private $_defaultReturnValue = null;
/**
* Temporaly stored position of argument to return. It's used by CEC_Hook::executeAndReturn()
* to store/extract the return value into/from arguments list.
* @var int
*/
static private $_returnArgumentPos = 1;
/**
* Temporaly setting of an execution conditions.
*
* @deprecated Function is no more needed, still exists due to downwards compatibility!
*
* This is usefull, if at least on of defined cec functions returns a specific value and the
* execution of further functions is no more needed.
*
* The defined condition will be reset in execute() method.
*
* @param mixed $condition One of CEC_Hook constants, with following control mechanism:
* - CEC_Hook::BREAK_AT_TRUE = Breaks the iteration of cec functions
* and returns the parameter, if the result of an function is true.
*
* - CEC_Hook::BREAK_AT_FALSE = Breaks the iteration of cec functions
* and returns the parameter, if the result of an function is false.
*
* - CEC_Hook::BREAK_AT_NULL = Breaks the iteration of cec functions
* and returns the parameter, if the result of an function is null.
*
* @param bool $overwriteArguments
* Flag to prevent overwriting of passed parameter to execute().
* Normally the parameter will be overwritten by return value of
* executed functions, but this is sometimes a not wanted side effect.
*
* @param bool $returnbreakconditiondirectly
* If a break condition is set and a chain function returns the condition
* set, setting this option forces the execute method to directly return
* that condition instead of the args
*
* @param mixed $defaultReturnValue
*
* @throws InvalidArgumentException If passed type is not one of CEC_Hook constants.
*/
public static function setConditions($condition, $overwriteArguments=true, $returnbreakconditiondirectly=false, $defaultReturnValue=null)
{
switch ($condition) {
case CEC_Hook::BREAK_AT_TRUE:
self::$_breakCondition = CEC_Hook::BREAK_AT_TRUE;
break;
case CEC_Hook::BREAK_AT_FALSE:
self::$_breakCondition = CEC_Hook::BREAK_AT_FALSE;
break;
case CEC_Hook::BREAK_AT_NULL:
self::$_breakCondition = CEC_Hook::BREAK_AT_NULL;
break;
default:
throw new InvalidArgumentException('Condition "' . $condition . '" is not supported!');
break;
}
self::$_overwriteArguments = (bool) $overwriteArguments;
self::$_returnBreakConditionDirectly = (bool) $returnbreakconditiondirectly;
self::$_defaultReturnValue = $defaultReturnValue;
}
/**
* Temporaly setting of break condition and optional the default return value.
*
* @param mixed $condition
* @param mixed $defaultReturnValue
* @return void
*/
public static function setBreakCondition($condition, $defaultReturnValue=null)
{
self::$_breakCondition = $condition;
self::setDefaultReturnValue($defaultReturnValue);
}
/**
* Temporaly setting of default return value.
*
* @param mixed $defaultReturnValue
* @return void
*/
public static function setDefaultReturnValue($defaultReturnValue)
{
self::$_defaultReturnValue = $defaultReturnValue;
}
/**
* Temporaly setting of position in argument to return.
*
* @param int $pos Position, feasible value greater 0
* @return void
*/
public static function setReturnArgumentPos($pos)
{
if ((int) $pos < 1) {
throw new Exception('Invalid return position');
}
self::$_returnArgumentPos = (int) $pos;
}
/**
* Method to execute registered functions for Contenido Extension Chainer (CEC).
*
* Gets the desired CEC iterator and executes each registered chain function by passing the achieved
* arguments to it. There is
*
* @param string $chainName The chain name to process
* @param mixed $param1 First parameter which will be forwarded to registered chain functions
* @param mixed $param2 Second parameter which will be forwarded to registered chain functions
* @param mixed $param3 Third parameter which will be forwarded to registered chain functions
* NOTE: There is no restriction for number of passed parameter.
* @return void
*/
public static function execute()
{
// get arguments
$args = func_get_args();
// get chainname
$chainName = array_shift($args);
// process CEC
$cecIterator = cApiCECRegistry::getInstance()->getIterator($chainName);
if ($cecIterator->count() > 0) {
$cecIterator->reset();
while ($chainEntry = $cecIterator->next()) {
// invoke CEC function
$chainEntry->setTemporaryArguments($args);
$chainEntry->execute();
}
}
// reset properties to defaults
self::_reset();
}
/**
* Method to execute registered functions for Contenido Extension Chainer (CEC).
*
* Gets the desired CEC iterator and executes each registered chain function. You can pass as much
* parameter as you want.
*
* @param string $chainName The chain name to process
* @param mixed $param1 First parameter which will be forwarded to registered chain functions
* @param mixed $param2 Second parameter which will be forwarded to registered chain functions
* @param mixed $param3 Third parameter which will be forwarded to registered chain functions
* NOTE: There is no restriction for number of passed parameter.
* @return mixed Parameter changed/processed by chain functions.
* Note: If no chain function is registered, the first parameter $param after
* $chainName will be returned
*/
public static function executeAndReturn()
{
// get arguments
$args = func_get_args();
// get chainname
$chainName = array_shift($args);
// position of return value in arguments list
$pos = self::$_returnArgumentPos - 1;
// default return value
$return = self::$_defaultReturnValue;
// process CEC
$cecIterator = cApiCECRegistry::getInstance()->getIterator($chainName);
if ($cecIterator->count() > 0) {
$cecIterator->reset();
while ($chainEntry = $cecIterator->next()) {
// invoke CEC function
$chainEntry->setTemporaryArguments($args);
$return = $chainEntry->execute();
if (isset($args[$pos])) {
$args[$pos] = $return;
}
}
}
if (isset($args[$pos])) {
$return = $args[$pos];
}
// reset properties to defaults
self::_reset();
return $return;
}
/**
* CEC function to process chains untill a break condition occurs.
*
* Gets the desired CEC iterator and executes each registered chain function as long as defined break
* condition doesn't occur.
*
* @param string $chainName The chain name to process
* @param mixed $param1 First parameter which will be forwarded to registered chain functions
* @param mixed $param2 Second parameter which will be forwarded to registered chain functions
* @param mixed $param3 Third parameter which will be forwarded to registered chain functions
* NOTE: There is no restriction for number of passed parameter.
* @return mixed The break condition or it's default value
*/
public static function executeWhileBreakCondition()
{
// get arguments
$args = func_get_args();
// get chainname
$chainName = array_shift($args);
// break condition and default return value
$breakCondition = self::$_breakCondition;
$return = self::$_defaultReturnValue;
// process CEC
$cecIterator = cApiCECRegistry::getInstance()->getIterator($chainName);
if ($cecIterator->count() > 0) {
$cecIterator->reset();
while ($chainEntry = $cecIterator->next()) {
// invoke CEC function
$chainEntry->setTemporaryArguments($args);
$return = $chainEntry->execute();
// process return value
if (isset($return) && $return === $breakCondition) {
self::_reset();
return $return;
break;
}
}
}
// reset properties to defaults
self::_reset();
return $return;
}
/**
* Resets some properties to defaults
*
* @return void
*/
private static function _reset()
{
self::$_breakCondition = null;
self::$_returnBreakConditionDirectly = false;
self::$_overwriteArguments = true;
self::$_defaultReturnValue = null;
self::$_returnArgumentPos = 1;
}
/**
* Used to debug some status informations.
*
* Writes the debug value into a logfile (see contenido/logs/cec_hook_debug.log).
*
* @param mixed $var The variable to dump
* @param string $msg Additional message
* @return void
*/
private static function _debug($var, $msg='')
{
$content = ($msg !== '') ? $msg . ': ' : '';
if (is_object($var) || is_array($var)) {
$content .= print_r($var, true);
} else {
$content .= $var . "\n";
}
$sLogPathName = $GLOBALS['cfg']['path']['contenido'] . 'logs/cec_hook_debug.log';
file_put_contents($sLogPathName, $content . "\n", FILE_APPEND);
}
}