1: <?php
2: /**
3: * This file contains the CEC hook class.
4: *
5: * @package Core
6: * @subpackage CEC
7: * @version SVN Revision $Rev:$
8: *
9: * @author Timo A. Hummel
10: * @author Murat Purc <murat@purc.de>
11: * @copyright four for business AG <www.4fb.de>
12: * @license http://www.contenido.org/license/LIZENZ.txt
13: * @link http://www.4fb.de
14: * @link http://www.contenido.org
15: */
16:
17: defined('CON_FRAMEWORK') || die('Illegal call: Missing framework initialization - request aborted.');
18:
19: /**
20: * Static CEC Hook class, provides some public methods to process registered
21: * chains at CEC (CONTENIDO Extension Chainer).
22: *
23: * Usage:
24: * <code>
25: * // example of executing a cec without a parameter and return value
26: * cApiCecHook::execute('Contenido.Content.Somewhere');
27: *
28: * // example of executing a cec with a parameter but without a return value
29: * $param = 'some value';
30: * cApiCecHook::execute('Contenido.Content.Somewhere', $param);
31: *
32: * // example of executing a cec with multiple parameter but without a return
33: * value
34: * $param = array('foo' => $bar, 'foo2' => $bar2);
35: * $param = cApiCecHook::execute('Contenido.Content.Somewhere', $param);
36: *
37: * // example of executing a cec without a parameter but a return value (with
38: * predefined
39: * // default return value)
40: * cApiCecHook::setDefaultReturnValue('this is the default title');
41: * $title = cApiCecHook::executeAndReturn('Contenido.Content.CreateTitletag');
42: *
43: * // example of executing a cec with a parameter and a return value
44: * // (usually the modified version of passed parameter)
45: * $baseHref = cRegistry::getFrontendUrl();
46: * $newBaseHref =
47: * cApiCecHook::executeAndReturn('Contenido.Frontend.BaseHrefGeneration',
48: * $baseHref);
49: *
50: * // example of executing a cec with a break condition and default return value
51: * cApiCecHook::setBreakCondition(false, true); // break condition = "false",
52: * default return value = "true"
53: * $allow =
54: * cApiCecHook::executeWhileBreakCondition('Contenido.Frontend.AllowEdit',
55: * $lang, $idcat, $idart, $auth->auth['uid']);
56: * if ($allow == false) {
57: * die('You're not coming in!');
58: * }
59: *
60: * // another example of executing a cec with a break condition and default
61: * return value
62: * cApiCecHook::setBreakCondition(true, false); // break condition = "true",
63: * default return value = "false"
64: * $allow =
65: * cApiCecHook::executeWhileBreakCondition('Contenido.Frontend.CategoryAccess',
66: * $lang, $idcat, $auth->auth['uid']);
67: * if ($allow == false) {
68: * die('I said, you're not coming in!');
69: * }
70: * </code>
71: *
72: * @package Core
73: * @subpackage CEC
74: */
75: class cApiCecHook {
76:
77: /**
78: * Temporaly stored break condition.
79: *
80: * @var int
81: */
82: private static $_breakCondition = NULL;
83:
84: /**
85: * Temporaly stored default return value of CEC functions
86: *
87: * @var mixed
88: */
89: private static $_defaultReturnValue = NULL;
90:
91: /**
92: * Temporaly stored position of argument to return.
93: * It's used by cApiCecHook::executeAndReturn()
94: * to store/extract the return value into/from arguments list.
95: *
96: * @var int
97: */
98: private static $_returnArgumentPos = 1;
99:
100: /**
101: * Temporaly setting of break condition and optional the default return
102: * value.
103: *
104: * @param mixed $condition
105: * @param mixed $defaultReturnValue
106: */
107: public static function setBreakCondition($condition, $defaultReturnValue = NULL) {
108: self::$_breakCondition = $condition;
109: self::setDefaultReturnValue($defaultReturnValue);
110: }
111:
112: /**
113: * Temporaly setting of default return value.
114: *
115: * @param mixed $defaultReturnValue
116: */
117: public static function setDefaultReturnValue($defaultReturnValue) {
118: self::$_defaultReturnValue = $defaultReturnValue;
119: }
120:
121: /**
122: * Temporaly setting of position in argument to return.
123: *
124: * @param int $pos Position, feasible value greater 0
125: *
126: * @throws cInvalidArgumentException if the given position is less than 1
127: */
128: public static function setReturnArgumentPos($pos) {
129: if ((int) $pos < 1) {
130: throw new cInvalidArgumentException('Return position has to be greater or equal than 1.');
131: }
132: self::$_returnArgumentPos = (int) $pos;
133: }
134:
135: /**
136: * Method to execute registered functions for CONTENIDO Extension Chainer
137: * (CEC).
138: * Gets the desired CEC iterator and executes each registered chain function
139: * by passing the given arguments to it. NOTE: the first param is interpeted
140: * as $chainName. NOTE: There is no restriction for number of passed
141: * parameter.
142: */
143: public static function execute() {
144: // get arguments
145: $args = func_get_args();
146:
147: // get chainname
148: $chainName = array_shift($args);
149:
150: // process CEC
151: $cecIterator = cApiCecRegistry::getInstance()->getIterator($chainName);
152: if ($cecIterator->count() > 0) {
153: $cecIterator->reset();
154:
155: while (($chainEntry = $cecIterator->next()) !== false) {
156: // invoke CEC function
157: $chainEntry->setTemporaryArguments($args);
158: $chainEntry->execute();
159: }
160: }
161:
162: // reset properties to defaults
163: self::_reset();
164: }
165:
166: /**
167: * Method to execute registered functions for CONTENIDO Extension Chainer
168: * (CEC).
169: * Gets the desired CEC iterator and executes each registered chain
170: * function. You can pass as much parameters as you want. NOTE: the first
171: * param is interpeted as $chainName. NOTE: There is no restriction for
172: * number of passed parameter. NOTE: If no chain function is registered,
173: * $_defaultReturnValue will be returned.
174: *
175: * @return mixed 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 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 The variable to dump
279: * @param string $msg Additional message
280: */
281: private static function _debug($var, $msg = '') {
282: global $cfg;
283:
284: $content = ($msg !== '') ? $msg . ': ' : '';
285: if (is_object($var) || is_array($var)) {
286: $content .= print_r($var, true);
287: } else {
288: $content .= $var . "\n";
289: }
290:
291: $sLogPathName = $cfg['path']['contenido_logs'] . 'cec_hook_debug.log';
292: cFileHandler::write($sLogPathName, $content . "\n", true);
293:
294: cDebug::out($content);
295: }
296: }
297:
298: