1: <?php
2: /**
3: * This file contains the CEC hook class.
4: *
5: * @package Core
6: * @subpackage CEC
7: * @author Timo A. Hummel
8: * @author Murat Purc <murat@purc.de>
9: * @copyright four for business AG <www.4fb.de>
10: * @license http://www.contenido.org/license/LIZENZ.txt
11: * @link http://www.4fb.de
12: * @link http://www.contenido.org
13: */
14:
15: defined('CON_FRAMEWORK') || die('Illegal call: Missing framework initialization - request aborted.');
16:
17: /**
18: * Static CEC Hook class, provides some public methods to process registered
19: * chains at CEC (CONTENIDO Extension Chainer).
20: *
21: * Usage:
22: * <code>
23: * // example of executing a cec without a parameter and return value
24: * cApiCecHook::execute('Contenido.Content.Somewhere');
25: *
26: * // example of executing a cec with a parameter but without a return value
27: * $param = 'some value';
28: * cApiCecHook::execute('Contenido.Content.Somewhere', $param);
29: *
30: * // example of executing a cec with multiple parameter but without a return
31: * value
32: * $param = array('foo' => $bar, 'foo2' => $bar2);
33: * $param = cApiCecHook::execute('Contenido.Content.Somewhere', $param);
34: *
35: * // example of executing a cec without a parameter but a return value (with
36: * predefined
37: * // default return value)
38: * cApiCecHook::setDefaultReturnValue('this is the default title');
39: * $title = cApiCecHook::executeAndReturn('Contenido.Content.CreateTitletag');
40: *
41: * // example of executing a cec with a parameter and a return value
42: * // (usually the modified version of passed parameter)
43: * $baseHref = cRegistry::getFrontendUrl();
44: * $newBaseHref =
45: * cApiCecHook::executeAndReturn('Contenido.Frontend.BaseHrefGeneration',
46: * $baseHref);
47: *
48: * // example of executing a cec with a break condition and default return value
49: * cApiCecHook::setBreakCondition(false, true); // break condition = "false",
50: * default return value = "true"
51: * $allow =
52: * cApiCecHook::executeWhileBreakCondition('Contenido.Frontend.AllowEdit',
53: * $lang, $idcat, $idart, $auth->auth['uid']);
54: * if ($allow == false) {
55: * die('You're not coming in!');
56: * }
57: *
58: * // another example of executing a cec with a break condition and default
59: * return value
60: * cApiCecHook::setBreakCondition(true, false); // break condition = "true",
61: * default return value = "false"
62: * $allow =
63: * cApiCecHook::executeWhileBreakCondition('Contenido.Frontend.CategoryAccess',
64: * $lang, $idcat, $auth->auth['uid']);
65: * if ($allow == false) {
66: * die('I said, you're not coming in!');
67: * }
68: * </code>
69: *
70: * @package Core
71: * @subpackage CEC
72: */
73: class cApiCecHook {
74:
75: /**
76: * Temporaly stored break condition.
77: *
78: * @var int
79: */
80: private static $_breakCondition = NULL;
81:
82: /**
83: * Temporaly stored default return value of CEC functions
84: *
85: * @var mixed
86: */
87: private static $_defaultReturnValue = NULL;
88:
89: /**
90: * Temporaly stored position of argument to return.
91: * It's used by cApiCecHook::executeAndReturn()
92: * to store/extract the return value into/from arguments list.
93: *
94: * @var int
95: */
96: private static $_returnArgumentPos = 1;
97:
98: /**
99: * Temporaly setting of break condition and optional the default return
100: * value.
101: *
102: * @param mixed $condition
103: * @param mixed $defaultReturnValue [optional]
104: */
105: public static function setBreakCondition($condition, $defaultReturnValue = NULL) {
106: self::$_breakCondition = $condition;
107: self::setDefaultReturnValue($defaultReturnValue);
108: }
109:
110: /**
111: * Temporaly setting of default return value.
112: *
113: * @param mixed $defaultReturnValue
114: */
115: public static function setDefaultReturnValue($defaultReturnValue) {
116: self::$_defaultReturnValue = $defaultReturnValue;
117: }
118:
119: /**
120: * Temporaly setting of position in argument to return.
121: *
122: * @param int $pos
123: * Position, feasible value greater 0
124: * @throws cInvalidArgumentException if the given position is less than 1
125: */
126: public static function setReturnArgumentPos($pos) {
127: if ((int) $pos < 1) {
128: throw new cInvalidArgumentException('Return position has to be greater or equal than 1.');
129: }
130: self::$_returnArgumentPos = (int) $pos;
131: }
132:
133: /**
134: * Method to execute registered functions for CONTENIDO Extension Chainer
135: * (CEC).
136: * Gets the desired CEC iterator and executes each registered chain function
137: * by passing the given arguments to it. NOTE: the first param is interpeted
138: * as $chainName. NOTE: There is no restriction for number of passed
139: * parameter.
140: */
141: public static function execute() {
142: // get arguments
143: $args = func_get_args();
144:
145: // get chainname
146: $chainName = array_shift($args);
147:
148: // process CEC
149: $cecIterator = cApiCecRegistry::getInstance()->getIterator($chainName);
150: if ($cecIterator->count() > 0) {
151: $cecIterator->reset();
152:
153: while (($chainEntry = $cecIterator->next()) !== false) {
154: // invoke CEC function
155: $chainEntry->setTemporaryArguments($args);
156: $chainEntry->execute();
157: }
158: }
159:
160: // reset properties to defaults
161: self::_reset();
162: }
163:
164: /**
165: * Method to execute registered functions for CONTENIDO Extension Chainer
166: * (CEC).
167: * Gets the desired CEC iterator and executes each registered chain
168: * function. You can pass as much parameters as you want. NOTE: the first
169: * param is interpeted as $chainName. NOTE: There is no restriction for
170: * number of passed parameter. NOTE: If no chain function is registered,
171: * $_defaultReturnValue will be returned.
172: *
173: * @return mixed
174: * Parameter changed/processed by chain functions.
175: */
176: public static function executeAndReturn() {
177: // get arguments
178: $args = func_get_args();
179:
180: // get chainname
181: $chainName = array_shift($args);
182:
183: // position of return value in arguments list
184: $pos = self::$_returnArgumentPos - 1;
185:
186: // default return value
187: $return = self::$_defaultReturnValue;
188:
189: // process CEC
190: $cecIterator = cApiCecRegistry::getInstance()->getIterator($chainName);
191: if ($cecIterator->count() > 0) {
192: $cecIterator->reset();
193:
194: while (($chainEntry = $cecIterator->next()) !== false) {
195: // invoke CEC function
196: $chainEntry->setTemporaryArguments($args);
197: $return = $chainEntry->execute();
198: if (isset($args[$pos])) {
199: $args[$pos] = $return;
200: }
201: }
202: }
203:
204: if (isset($args[$pos])) {
205: $return = $args[$pos];
206: }
207:
208: // reset properties to defaults
209: self::_reset();
210:
211: return $return;
212: }
213:
214: /**
215: * CEC function to process chains untill a break condition occurs.
216: *
217: * Gets the desired CEC iterator and executes each registered chain function
218: * as long as defined break condition doesn't occur. NOTE: the first
219: * param is interpeted as $chainName. NOTE: There is no restriction for
220: * number of passed parameter. NOTE: If no chain function is registered,
221: * $_defaultReturnValue will be returned.
222: *
223: * @return mixed
224: * The break condition or it's default value
225: */
226: public static function executeWhileBreakCondition() {
227: // get arguments
228: $args = func_get_args();
229:
230: // get chainname
231: $chainName = array_shift($args);
232:
233: // break condition and default return value
234: $breakCondition = self::$_breakCondition;
235: $return = self::$_defaultReturnValue;
236:
237: // process CEC
238: $cecIterator = cApiCecRegistry::getInstance()->getIterator($chainName);
239: if ($cecIterator->count() > 0) {
240: $cecIterator->reset();
241:
242: while (($chainEntry = $cecIterator->next()) !== false) {
243: // invoke CEC function
244: $chainEntry->setTemporaryArguments($args);
245: $return = $chainEntry->execute();
246: // process return value
247: if (isset($return) && $return === $breakCondition) {
248: self::_reset();
249:
250: return $return;
251: break;
252: }
253: }
254: }
255:
256: // reset properties to defaults
257: self::_reset();
258:
259: return $return;
260: }
261:
262: /**
263: * Resets some properties to defaults
264: */
265: private static function _reset() {
266: self::$_breakCondition = NULL;
267: self::$_defaultReturnValue = NULL;
268: self::$_returnArgumentPos = 1;
269: }
270:
271: /**
272: * Used to debug some status informations.
273: *
274: * @todo Implement cec_hook debug mode for automatic logging when activated.
275: * Writes the debug value into a logfile (see
276: * contenido/data/log/cec_hook_debug.log).
277: *
278: * @param mixed $var
279: * The variable to dump
280: * @param string $msg [optional]
281: * Additional message
282: */
283: private static function _debug($var, $msg = '') {
284: global $cfg;
285:
286: $content = ($msg !== '') ? $msg . ': ' : '';
287: if (is_object($var) || is_array($var)) {
288: $content .= print_r($var, true);
289: } else {
290: $content .= $var . "\n";
291: }
292:
293: $sLogPathName = $cfg['path']['contenido_logs'] . 'cec_hook_debug.log';
294: cFileHandler::write($sLogPathName, $content . "\n", true);
295:
296: cDebug::out($content);
297: }
298: }
299:
300: