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: *
125: * @throws cInvalidArgumentException if the given position is less than 1
126: */
127: public static function setReturnArgumentPos($pos) {
128: if ((int) $pos < 1) {
129: throw new cInvalidArgumentException('Return position has to be greater or equal than 1.');
130: }
131: self::$_returnArgumentPos = (int) $pos;
132: }
133:
134: /**
135: * Method to execute registered functions for CONTENIDO Extension Chainer
136: * (CEC).
137: * Gets the desired CEC iterator and executes each registered chain function
138: * by passing the given arguments to it. NOTE: the first param is interpeted
139: * as $chainName. NOTE: There is no restriction for number of passed
140: * parameter.
141: */
142: public static function execute() {
143: // get arguments
144: $args = func_get_args();
145:
146: // get chainname
147: $chainName = array_shift($args);
148:
149: // process CEC
150: $cecIterator = cApiCecRegistry::getInstance()->getIterator($chainName);
151: if ($cecIterator->count() > 0) {
152: $cecIterator->reset();
153:
154: while (($chainEntry = $cecIterator->next()) !== false) {
155: // invoke CEC function
156: $chainEntry->setTemporaryArguments($args);
157: $chainEntry->execute();
158: }
159: }
160:
161: // reset properties to defaults
162: self::_reset();
163: }
164:
165: /**
166: * Method to execute registered functions for CONTENIDO Extension Chainer
167: * (CEC).
168: * Gets the desired CEC iterator and executes each registered chain
169: * function. You can pass as much parameters as you want. NOTE: the first
170: * param is interpeted as $chainName. NOTE: There is no restriction for
171: * number of passed parameter. NOTE: If no chain function is registered,
172: * $_defaultReturnValue will be returned.
173: *
174: * @return mixed
175: * Parameter changed/processed by chain functions.
176: */
177: public static function executeAndReturn() {
178: // get arguments
179: $args = func_get_args();
180:
181: // get chainname
182: $chainName = array_shift($args);
183:
184: // position of return value in arguments list
185: $pos = self::$_returnArgumentPos - 1;
186:
187: // default return value
188: $return = self::$_defaultReturnValue;
189:
190: // process CEC
191: $cecIterator = cApiCecRegistry::getInstance()->getIterator($chainName);
192: if ($cecIterator->count() > 0) {
193: $cecIterator->reset();
194:
195: while (($chainEntry = $cecIterator->next()) !== false) {
196: // invoke CEC function
197: $chainEntry->setTemporaryArguments($args);
198: $return = $chainEntry->execute();
199: if (isset($args[$pos])) {
200: $args[$pos] = $return;
201: }
202: }
203: }
204:
205: if (isset($args[$pos])) {
206: $return = $args[$pos];
207: }
208:
209: // reset properties to defaults
210: self::_reset();
211:
212: return $return;
213: }
214:
215: /**
216: * CEC function to process chains untill a break condition occurs.
217: *
218: * Gets the desired CEC iterator and executes each registered chain function
219: * as long as defined break condition doesn't occur. NOTE: the first
220: * param is interpeted as $chainName. NOTE: There is no restriction for
221: * number of passed parameter. NOTE: If no chain function is registered,
222: * $_defaultReturnValue will be returned.
223: *
224: * @return mixed
225: * The break condition or it's default value
226: */
227: public static function executeWhileBreakCondition() {
228: // get arguments
229: $args = func_get_args();
230:
231: // get chainname
232: $chainName = array_shift($args);
233:
234: // break condition and default return value
235: $breakCondition = self::$_breakCondition;
236: $return = self::$_defaultReturnValue;
237:
238: // process CEC
239: $cecIterator = cApiCecRegistry::getInstance()->getIterator($chainName);
240: if ($cecIterator->count() > 0) {
241: $cecIterator->reset();
242:
243: while (($chainEntry = $cecIterator->next()) !== false) {
244: // invoke CEC function
245: $chainEntry->setTemporaryArguments($args);
246: $return = $chainEntry->execute();
247: // process return value
248: if (isset($return) && $return === $breakCondition) {
249: self::_reset();
250: return $return;
251: }
252: }
253: }
254:
255: // reset properties to defaults
256: self::_reset();
257:
258: return $return;
259: }
260:
261: /**
262: * Resets some properties to defaults
263: */
264: private static function _reset() {
265: self::$_breakCondition = NULL;
266: self::$_defaultReturnValue = NULL;
267: self::$_returnArgumentPos = 1;
268: }
269:
270: /**
271: * Used to debug some status informations.
272: *
273: * @todo Implement cec_hook debug mode for automatic logging when activated.
274: * Writes the debug value into a logfile (see
275: * contenido/data/log/cec_hook_debug.log).
276: *
277: * @param mixed $var
278: * The variable to dump
279: * @param string $msg [optional]
280: * Additional message
281: *
282: * @throws cInvalidArgumentException
283: */
284: private static function _debug($var, $msg = '') {
285: global $cfg;
286:
287: $content = ($msg !== '') ? $msg . ': ' : '';
288: if (is_object($var) || is_array($var)) {
289: $content .= print_r($var, true);
290: } else {
291: $content .= $var . "\n";
292: }
293:
294: $sLogPathName = $cfg['path']['contenido_logs'] . 'cec_hook_debug.log';
295: cFileHandler::write($sLogPathName, $content . "\n", true);
296:
297: cDebug::out($content);
298: }
299: }
300:
301: