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 [optional]
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
125: * Position, feasible value greater 0
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
176: * Parameter changed/processed by chain functions.
177: */
178: public static function executeAndReturn() {
179: // get arguments
180: $args = func_get_args();
181:
182: // get chainname
183: $chainName = array_shift($args);
184:
185: // position of return value in arguments list
186: $pos = self::$_returnArgumentPos - 1;
187:
188: // default return value
189: $return = self::$_defaultReturnValue;
190:
191: // process CEC
192: $cecIterator = cApiCecRegistry::getInstance()->getIterator($chainName);
193: if ($cecIterator->count() > 0) {
194: $cecIterator->reset();
195:
196: while (($chainEntry = $cecIterator->next()) !== false) {
197: // invoke CEC function
198: $chainEntry->setTemporaryArguments($args);
199: $return = $chainEntry->execute();
200: if (isset($args[$pos])) {
201: $args[$pos] = $return;
202: }
203: }
204: }
205:
206: if (isset($args[$pos])) {
207: $return = $args[$pos];
208: }
209:
210: // reset properties to defaults
211: self::_reset();
212:
213: return $return;
214: }
215:
216: /**
217: * CEC function to process chains untill a break condition occurs.
218: *
219: * Gets the desired CEC iterator and executes each registered chain function
220: * as long as defined break condition doesn't occur. NOTE: the first
221: * param is interpeted as $chainName. NOTE: There is no restriction for
222: * number of passed parameter. NOTE: If no chain function is registered,
223: * $_defaultReturnValue will be returned.
224: *
225: * @return mixed
226: * The break condition or it's default value
227: */
228: public static function executeWhileBreakCondition() {
229: // get arguments
230: $args = func_get_args();
231:
232: // get chainname
233: $chainName = array_shift($args);
234:
235: // break condition and default return value
236: $breakCondition = self::$_breakCondition;
237: $return = self::$_defaultReturnValue;
238:
239: // process CEC
240: $cecIterator = cApiCecRegistry::getInstance()->getIterator($chainName);
241: if ($cecIterator->count() > 0) {
242: $cecIterator->reset();
243:
244: while (($chainEntry = $cecIterator->next()) !== false) {
245: // invoke CEC function
246: $chainEntry->setTemporaryArguments($args);
247: $return = $chainEntry->execute();
248: // process return value
249: if (isset($return) && $return === $breakCondition) {
250: self::_reset();
251:
252: return $return;
253: break;
254: }
255: }
256: }
257:
258: // reset properties to defaults
259: self::_reset();
260:
261: return $return;
262: }
263:
264: /**
265: * Resets some properties to defaults
266: */
267: private static function _reset() {
268: self::$_breakCondition = NULL;
269: self::$_defaultReturnValue = NULL;
270: self::$_returnArgumentPos = 1;
271: }
272:
273: /**
274: * Used to debug some status informations.
275: *
276: * @todo Implement cec_hook debug mode for automatic logging when activated.
277: * Writes the debug value into a logfile (see
278: * contenido/data/log/cec_hook_debug.log).
279: *
280: * @param mixed $var
281: * The variable to dump
282: * @param string $msg [optional]
283: * Additional message
284: */
285: private static function _debug($var, $msg = '') {
286: global $cfg;
287:
288: $content = ($msg !== '') ? $msg . ': ' : '';
289: if (is_object($var) || is_array($var)) {
290: $content .= print_r($var, true);
291: } else {
292: $content .= $var . "\n";
293: }
294:
295: $sLogPathName = $cfg['path']['contenido_logs'] . 'cec_hook_debug.log';
296: cFileHandler::write($sLogPathName, $content . "\n", true);
297:
298: cDebug::out($content);
299: }
300: }
301:
302: