1: <?php
  2: /**
  3:  * This file contains the CEC registry 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:  * CEC registry class.
 21:  * Used to register chains and chain functions to invoke.
 22:  *
 23:  * Following 3 types of CEC functions/callbacks are supported at the moment:
 24:  * - Callbacks, which should only be invoked. They don't return a value and have
 25:  * no
 26:  * break conditions, @see cApiCecHook::execute()
 27:  * - Callbacks, which should return a value and/or should modify a passed
 28:  * parameter,
 29:  *
 30:  * @see cApiCecHook::executeAndReturn() - Callbacks, which should be processed
 31:  *      untill a defined break condition achieves,
 32:  * @see cApiCecHook::executeWhileBreakCondition()
 33:  *
 34:  * @package Core
 35:  * @subpackage CEC
 36:  */
 37: class cApiCecRegistry {
 38: 
 39:     /**
 40:      * List of available chains
 41:      *
 42:      * @var array
 43:      */
 44:     private $_aChains;
 45: 
 46:     /**
 47:      * Self instance
 48:      *
 49:      * @var cApiCecRegistry
 50:      */
 51:     private static $_instance = NULL;
 52: 
 53:     /**
 54:      * Constructor
 55:      */
 56:     protected function __construct() {
 57:         $this->_aChains = array();
 58:     }
 59: 
 60:     /**
 61:      * Prevent cloning
 62:      */
 63:     private function __clone() {
 64:         // donut
 65:     }
 66: 
 67:     /**
 68:      * Returns a instance of cApiCecRegistry
 69:      *
 70:      * @return cApiCecRegistry
 71:      */
 72:     public static function getInstance() {
 73:         if (self::$_instance == NULL) {
 74:             self::$_instance = new cApiCecRegistry();
 75:         }
 76: 
 77:         return self::$_instance;
 78:     }
 79: 
 80:     /**
 81:      * Registers a chain (adds the chain to the internal chain holder)
 82:      * NOTE: The number of parameter is not restricted.
 83:      * You can pass
 84:      * as much parameter as you want.
 85:      *
 86:      * @param string $sChainName
 87:      */
 88:     public function registerChain($sChainName) {
 89:         $aParam = array();
 90:         $iNumArgs = func_num_args();
 91: 
 92:         for ($iCount = 0; $iCount < $iNumArgs; $iCount++) {
 93:             $aParam[$iCount] = func_get_arg($iCount);
 94:         }
 95: 
 96:         $this->_addChain($sChainName, $aParam);
 97:     }
 98: 
 99:     /**
100:      * Unregisters a chain
101:      *
102:      * @param string $sChainName
103:      *
104:      * @throws cInvalidArgumentException if the given chain does not exist
105:      */
106:     public function unregisterChain($sChainName) {
107:         // Check if the chain exists
108:         if (!$this->isChainRegistered($sChainName)) {
109:             throw new cInvalidArgumentException('Chain ' . $sChainName . ' doesn\'t exist.');
110:         }
111: 
112:         $functions = array();
113:         $this->_resetIterator($sChainName);
114:         $chainFunctions = $this->_aChains[$sChainName]['functions'];
115:         foreach ($chainFunctions as $pos => $item) {
116:             $functions[] = $item->getFunctionName();
117:         }
118: 
119:         foreach ($functions as $p => $func) {
120:             $this->removeChainFunction($sChainName, $func);
121:         }
122: 
123:         unset($this->_aChains[$sChainName]);
124:     }
125: 
126:     /**
127:      * Checks if a chain is registered or not.
128:      *
129:      * @param string $sChainName
130:      *
131:      * @return bool
132:      */
133:     public function isChainRegistered($sChainName) {
134:         return (isset($this->_aChains[$sChainName]));
135:     }
136: 
137:     /**
138:      * Returns list of registered chain names
139:      *
140:      * @return array
141:      */
142:     public function getRegisteredChainNames() {
143:         return array_keys($this->_aChains);
144:     }
145: 
146:     /**
147:      * Adds the chain to the internal chain holder
148:      *
149:      * @param string $sChainName Chain name
150:      * @param array $aParameters Chain parameter
151:      */
152:     protected function _addChain($sChainName, array $aParameters = array()) {
153:         $cfg = cRegistry::getConfig();
154:         // do not add the chain if the chain system is disabled
155:         if ($cfg['debug']['disable_chains']) {
156:             return;
157:         }
158: 
159:         $this->_aChains[$sChainName]['parameters'] = $aParameters;
160:         $this->_aChains[$sChainName]['functions'] = array();
161:     }
162: 
163:     /**
164:      * Adds a chain function which is to invoke.
165:      *
166:      * @param string $sChainName Chain name
167:      * @param string $sFunctionName Name of function/callback to invoke.
168:      *        Feasible values are:
169:      *        - "ClassName->methodName" to invoke a method of a ClassName
170:      *        instance.
171:      *        A instance of the clas will be created here.
172:      *        - "ClassName::methodName" to invoke a static method of ClassName.
173:      *        - "FunctionName" to invoke a function.
174:      *        NOTE: Necessary files must be manually included before or by
175:      *        defined autoloader.
176:      *
177:      * @throws cInvalidArgumentException if the given chain is not registered or
178:      *         the given callback is not callable
179:      * @return bool True on success, otherwhise false
180:      */
181:     public function addChainFunction($sChainName, $sFunctionName) {
182:         $cfg = cRegistry::getConfig();
183:         // do not add the chain if the chain system is disabled
184:         if ($cfg['debug']['disable_chains']) {
185:             return;
186:         }
187: 
188:         // Check if the chain exists
189:         if (!$this->isChainRegistered($sChainName)) {
190:             throw new cInvalidArgumentException('Chain ' . $sChainName . ' doesn\'t exist.');
191:         }
192: 
193:         if (strpos($sFunctionName, '->') > 0) {
194:             // chain function is a method of a object instance
195:             list($class, $method) = explode('->', $sFunctionName);
196:             if (!class_exists($class)) {
197:                 throw new cInvalidArgumentException('Class ' . $class . ' doesn\'t exist, can\'t add ' . $sFunctionName . ' to chain ' . $sChainName);
198:             } elseif (!method_exists($class, $method)) {
199:                 throw new cInvalidArgumentException('Method ' . $method . ' in class ' . $class . ' doesn\'t exist, can\'t add ' . $sFunctionName . ' to chain ' . $sChainName);
200:             }
201:             $call = array(
202:                 new $class(),
203:                 $method
204:             );
205:         } elseif (strpos($sFunctionName, '::') > 0) {
206:             // chain function is static method of a object
207:             list($class, $method) = explode('::', $sFunctionName);
208:             if (!class_exists($class)) {
209:                 throw new cInvalidArgumentException('Class ' . $class . ' doesn\'t exist, can\'t add ' . $sFunctionName . ' to chain ' . $sChainName);
210:             } elseif (!method_exists($class, $method)) {
211:                 throw new cInvalidArgumentException('Method ' . $method . ' in class ' . $class . ' doesn\'t exist, can\'t add ' . $sFunctionName . ' to chain ' . $sChainName);
212:             }
213:             $call = array(
214:                 $class,
215:                 $method
216:             );
217:         } else {
218:             // chain function is a function
219:             if (!function_exists($sFunctionName)) {
220:                 throw new cInvalidArgumentException('Function ' . $sFunctionName . ' doesn\'t exist, can\'t add to chain ' . $sChainName);
221:             }
222:             $call = $sFunctionName;
223:         }
224: 
225:         // Last check if the callback is callable
226:         if (!is_callable($call)) {
227:             throw new cInvalidArgumentException('Function ' . $sFunctionName . ' isn\'t callable, can\'t add to chain ' . $sChainName);
228:         }
229: 
230:         $oChainItem = new cApiCecChainItem($sChainName, $sFunctionName, $this->_aChains[$sChainName]['parameters']);
231:         $oChainItem->setCallback($call);
232:         $this->_aChains[$sChainName]['functions'][] = $oChainItem;
233: 
234:         return true;
235:     }
236: 
237:     /**
238:      * Checks if a chain function exists.
239:      *
240:      * @param string $sChainName Chain name
241:      * @param string $sFunctionName Name of function to check
242:      *
243:      * @return bool
244:      */
245:     public function chainFunctionExists($sChainName, $sFunctionName) {
246:         if (!$this->isChainRegistered($sChainName)) {
247:             return false;
248:         }
249: 
250:         $this->_resetIterator($sChainName);
251:         $chainFunctions = $this->_aChains[$sChainName]['functions'];
252:         foreach ($chainFunctions as $pos => $item) {
253:             if ($item->getFunctionName() == $sFunctionName) {
254:                 return true;
255:             }
256:         }
257: 
258:         return false;
259:     }
260: 
261:     /**
262:      * Removes a chain function.
263:      *
264:      * @param string $sChainName Chain name
265:      * @param string $sFunctionName Name of function to remove from chain.
266:      */
267:     public function removeChainFunction($sChainName, $sFunctionName) {
268:         if (!$this->isChainRegistered($sChainName)) {
269:             return;
270:         }
271: 
272:         $this->_resetIterator($sChainName);
273:         $chainFunctions = $this->_aChains[$sChainName]['functions'];
274:         foreach ($this->_aChains[$sChainName]['functions'] as $pos => $item) {
275:             if ($item->getFunctionName() == $sFunctionName) {
276:                 unset($this->_aChains[$sChainName]['functions'][$pos]);
277: 
278:                 return;
279:             }
280:         }
281:     }
282: 
283:     /**
284:      * Returns the iterator for a desired chain.
285:      *
286:      * @todo : cIterator should be replaced by ArrayIterator (@see
287:      *       http://www.php.net/spl)
288:      *       but ArrayIterator uses rewind() instead of reset()...
289:      *
290:      * @param string $sChainName Chain name
291:      *
292:      * @return cIterator
293:      */
294:     public function getIterator($sChainName) {
295:         return new cIterator($this->_aChains[$sChainName]['functions']);
296:     }
297: 
298:     /**
299:      * Resets the chain iterator.
300:      *
301:      * @param string $sChainName
302:      */
303:     protected function _resetIterator($sChainName) {
304:         $iterator = $this->getIterator($sChainName);
305:         $iterator->reset();
306:     }
307: }
308: 
309: /**
310:  * CEC chain item class.
311:  *
312:  * @package Core
313:  * @subpackage CEC
314:  */
315: class cApiCecChainItem {
316: 
317:     /**
318:      * Chain name
319:      *
320:      * @var string
321:      */
322:     protected $_sChainName;
323: 
324:     /**
325:      * Name of function to invoke
326:      *
327:      * @var string
328:      */
329:     protected $_sFunctionName;
330: 
331:     /**
332:      * Callback name.
333:      * Contains either the function name to invoke, or a indexed array
334:      * (class/object and method)
335:      * and it's method to execute.
336:      *
337:      * @var array string
338:      */
339:     protected $_mCallback;
340: 
341:     /**
342:      * Parameter to pass to the function
343:      *
344:      * @var array
345:      */
346:     protected $_aParameters;
347: 
348:     /**
349:      * Temporary arguments holder
350:      *
351:      * @var array NULL
352:      */
353:     protected $_mTemporaryArguments;
354: 
355:     /**
356:      * Constructor, sets the CEC chain item properties.
357:      *
358:      * @param string $sChainName
359:      * @param string $sFunctionName
360:      * @param array $aParameters
361:      */
362:     public function __construct($sChainName, $sFunctionName, $aParameters) {
363:         $this->setChainName($sChainName);
364:         $this->setFunctionName($sFunctionName);
365:         $this->setParameters($aParameters);
366:         $this->setCallback($this->getFunctionName());
367:     }
368: 
369:     /**
370:      * Sets the chain name
371:      *
372:      * @param string $sChainName
373:      */
374:     public function setChainName($sChainName) {
375:         $this->_sChainName = $sChainName;
376:     }
377: 
378:     /**
379:      * Returns the chain name
380:      *
381:      * @return string
382:      */
383:     public function getChainName() {
384:         return $this->_sChainName;
385:     }
386: 
387:     /**
388:      * Sets the function name
389:      *
390:      * @param string $sFunctionName
391:      */
392:     public function setFunctionName($sFunctionName) {
393:         $this->_sFunctionName = $sFunctionName;
394:     }
395: 
396:     /**
397:      * Returns the function name
398:      *
399:      * @return string
400:      */
401:     public function getFunctionName() {
402:         return $this->_sFunctionName;
403:     }
404: 
405:     /**
406:      * Sets the callback parameters
407:      *
408:      * @param array $aParameters
409:      */
410:     public function setParameters(array $aParameters) {
411:         $this->_aParameters = $aParameters;
412:     }
413: 
414:     /**
415:      * Returns the function name
416:      *
417:      * @return array
418:      */
419:     public function getParameters() {
420:         return $this->_aParameters;
421:     }
422: 
423:     /**
424:      * Sets the callback
425:      *
426:      * @param string|array $callback
427:      * @throws cInvalidArgumentException if the given callback is not a string
428:      *         or an array
429:      */
430:     public function setCallback($callback) {
431:         if (is_string($callback) || is_array($callback)) {
432:             $this->_mCallback = $callback;
433:         } else {
434:             throw new cInvalidArgumentException("Callback has to be a string or an array.");
435:         }
436:     }
437: 
438:     /**
439:      * Returns the callback
440:      *
441:      * @return string array
442:      */
443:     public function getCallback() {
444:         return $this->_mCallback;
445:     }
446: 
447:     /**
448:      * Another way to set the arguments before invoking execute() method.
449:      *
450:      * @param array $args
451:      */
452:     public function setTemporaryArguments(array $args = array()) {
453:         $this->_mTemporaryArguments = $args;
454:     }
455: 
456:     /**
457:      * Will be invoked by execute() method.
458:      * If temporary arguments where set before, it returns them and resets the
459:      * property.
460:      *
461:      * @return array
462:      */
463:     public function getTemporaryArguments() {
464:         $args = $this->_mTemporaryArguments;
465:         $this->_mTemporaryArguments = NULL;
466: 
467:         return $args;
468:     }
469: 
470:     /**
471:      * Invokes the CEC function/callback.
472:      *
473:      * @return mixed If available, the result of the CEC function/callback
474:      */
475:     public function execute() {
476:         // get temporary arguments, if the where set before
477:         if (!$args = $this->getTemporaryArguments()) {
478:             // no temporary arguments available, get them by func_get_args()
479:             $args = func_get_args();
480:         }
481: 
482:         return call_user_func_array($this->getCallback(), $args);
483:     }
484: }
485: