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:      *
 83:      * @param string $sChainName
 84:      * @param        mixed First chain parameter
 85:      * @param        mixed Second chain parameter
 86:      * @param        mixed Third chain parameter...
 87:      *                     NOTE: The number of parameter is not restricted, you can pass
 88:      *                     parameter as
 89:      *                     much as you want.
 90:      */
 91:     public function registerChain($sChainName) {
 92:         $aParam = array();
 93:         $iNumArgs = func_num_args();
 94: 
 95:         for ($iCount = 0; $iCount < $iNumArgs; $iCount++) {
 96:             $aParam[$iCount] = func_get_arg($iCount);
 97:         }
 98: 
 99:         $this->_addChain($sChainName, $aParam);
100:     }
101: 
102:     /**
103:      * Unregisters a chain
104:      *
105:      * @param string $sChainName
106:      *
107:      * @throws cInvalidArgumentException if the given chain does not exist
108:      */
109:     public function unregisterChain($sChainName) {
110:         // Check if the chain exists
111:         if (!$this->isChainRegistered($sChainName)) {
112:             throw new cInvalidArgumentException('Chain ' . $sChainName . ' doesn\'t exist.');
113:         }
114: 
115:         $functions = array();
116:         $this->_resetIterator($sChainName);
117:         $chainFunctions = $this->_aChains[$sChainName]['functions'];
118:         foreach ($chainFunctions as $pos => $item) {
119:             $functions[] = $item->getFunctionName();
120:         }
121: 
122:         foreach ($functions as $p => $func) {
123:             $this->removeChainFunction($sChainName, $func);
124:         }
125: 
126:         unset($this->_aChains[$sChainName]);
127:     }
128: 
129:     /**
130:      * Checks if a chain is registered or not.
131:      *
132:      * @param string $sChainName
133:      *
134:      * @return bool
135:      */
136:     public function isChainRegistered($sChainName) {
137:         return (isset($this->_aChains[$sChainName]));
138:     }
139: 
140:     /**
141:      * Returns list of registered chain names
142:      *
143:      * @return array
144:      */
145:     public function getRegisteredChainNames() {
146:         return array_keys($this->_aChains);
147:     }
148: 
149:     /**
150:      * Adds the chain to the internal chain holder
151:      *
152:      * @param string $sChainName  Chain name
153:      * @param array  $aParameters Chain parameter
154:      */
155:     protected function _addChain($sChainName, array $aParameters = array()) {
156:         $cfg = cRegistry::getConfig();
157:         // do not add the chain if the chain system is disabled
158:         if ($cfg['debug']['disable_chains']) {
159:             return;
160:         }
161: 
162:         $this->_aChains[$sChainName]['parameters'] = $aParameters;
163:         $this->_aChains[$sChainName]['functions'] = array();
164:     }
165: 
166:     /**
167:      * Adds a chain function which is to invoke.
168:      *
169:      * @param string $sChainName    Chain name
170:      * @param string $sFunctionName Name of function/callback to invoke.
171:      *                              Feasible values are:
172:      *        - "ClassName->methodName" to invoke a method of a ClassName
173:      *                              instance.
174:      *                              A instance of the clas will be created here.
175:      *        - "ClassName::methodName" to invoke a static method of ClassName.
176:      *        - "FunctionName" to invoke a function.
177:      *                              NOTE: Necessary files must be manually included before or by
178:      *                              defined autoloader.
179:      *
180:      * @throws cInvalidArgumentException if the given chain is not registered or the given callback is not callable
181:      * @return bool True on success, otherwhise false
182:      */
183:     public function addChainFunction($sChainName, $sFunctionName) {
184:         $cfg = cRegistry::getConfig();
185:         // do not add the chain if the chain system is disabled
186:         if ($cfg['debug']['disable_chains']) {
187:             return;
188:         }
189: 
190:         // Check if the chain exists
191:         if (!$this->isChainRegistered($sChainName)) {
192:             throw new cInvalidArgumentException('Chain ' . $sChainName . ' doesn\'t exist.');
193:         }
194: 
195:         if (strpos($sFunctionName, '->') > 0) {
196:             // chain function is a method of a object instance
197:             list($class, $method) = explode('->', $sFunctionName);
198:             if (!class_exists($class)) {
199:                 throw new cInvalidArgumentException('Class ' . $class . ' doesn\'t exist, can\'t add ' . $sFunctionName . ' to chain ' . $sChainName);
200:             } elseif (!method_exists($class, $method)) {
201:                 throw new cInvalidArgumentException('Method ' . $method . ' in class ' . $class . ' doesn\'t exist, can\'t add ' . $sFunctionName . ' to chain ' . $sChainName);
202:             }
203:             $call = array(
204:                 new $class(), $method
205:             );
206:         } elseif (strpos($sFunctionName, '::') > 0) {
207:             // chain function is static method of a object
208:             list($class, $method) = explode('::', $sFunctionName);
209:             if (!class_exists($class)) {
210:                 throw new cInvalidArgumentException('Class ' . $class . ' doesn\'t exist, can\'t add ' . $sFunctionName . ' to chain ' . $sChainName);
211:             } elseif (!method_exists($class, $method)) {
212:                 throw new cInvalidArgumentException('Method ' . $method . ' in class ' . $class . ' doesn\'t exist, can\'t add ' . $sFunctionName . ' to chain ' . $sChainName);
213:             }
214:             $call = array($class, $method);
215:         } else {
216:             // chain function is a function
217:             if (!function_exists($sFunctionName)) {
218:                 throw new cInvalidArgumentException('Function ' . $sFunctionName . ' doesn\'t exist, can\'t add to chain ' . $sChainName);
219:             }
220:             $call = $sFunctionName;
221:         }
222: 
223:         // Last check if the callback is callable
224:         if (!is_callable($call)) {
225:             throw new cInvalidArgumentException('Function ' . $sFunctionName . ' isn\'t callable, can\'t add to chain ' . $sChainName);
226:         }
227: 
228:         $oChainItem = new cApiCecChainItem($sChainName, $sFunctionName, $this->_aChains[$sChainName]['parameters']);
229:         $oChainItem->setCallback($call);
230:         $this->_aChains[$sChainName]['functions'][] = $oChainItem;
231: 
232:         return true;
233:     }
234: 
235:     /**
236:      * Checks if a chain function exists.
237:      *
238:      * @param string $sChainName    Chain name
239:      * @param string $sFunctionName Name of function to check
240:      *
241:      * @return bool
242:      */
243:     public function chainFunctionExists($sChainName, $sFunctionName) {
244:         if (!$this->isChainRegistered($sChainName)) {
245:             return false;
246:         }
247: 
248:         $this->_resetIterator($sChainName);
249:         $chainFunctions = $this->_aChains[$sChainName]['functions'];
250:         foreach ($chainFunctions as $pos => $item) {
251:             if ($item->getFunctionName() == $sFunctionName) {
252:                 return true;
253:             }
254:         }
255: 
256:         return false;
257:     }
258: 
259:     /**
260:      * Removes a chain function.
261:      *
262:      * @param string $sChainName    Chain name
263:      * @param string $sFunctionName Name of function to remove from chain.
264:      */
265:     public function removeChainFunction($sChainName, $sFunctionName) {
266:         if (!$this->isChainRegistered($sChainName)) {
267:             return;
268:         }
269: 
270:         $this->_resetIterator($sChainName);
271:         $chainFunctions = $this->_aChains[$sChainName]['functions'];
272:         foreach ($this->_aChains[$sChainName]['functions'] as $pos => $item) {
273:             if ($item->getFunctionName() == $sFunctionName) {
274:                 unset($this->_aChains[$sChainName]['functions'][$pos]);
275: 
276:                 return;
277:             }
278:         }
279:     }
280: 
281:     /**
282:      * Returns the iterator for a desired chain.
283:      *
284:      * @todo : cIterator should be replaced by ArrayIterator (@see
285:      *       http://www.php.net/spl)
286:      *       but ArrayIterator uses rewind() instead of reset()...
287:      *
288:      * @param string $sChainName Chain name
289:      *
290:      * @return cIterator
291:      */
292:     public function getIterator($sChainName) {
293:         return new cIterator($this->_aChains[$sChainName]['functions']);
294:     }
295: 
296:     /**
297:      * Resets the chain iterator.
298:      *
299:      * @param string $sChainName
300:      */
301:     protected function _resetIterator($sChainName) {
302:         $iterator = $this->getIterator($sChainName);
303:         $iterator->reset();
304:     }
305: 
306: }
307: 
308: /**
309:  * CEC chain item class.
310:  *
311:  * @package    Core
312:  * @subpackage CEC
313:  */
314: class cApiCecChainItem {
315: 
316:     /**
317:      * Chain name
318:      *
319:      * @var string
320:      */
321:     protected $_sChainName;
322: 
323:     /**
324:      * Name of function to invoke
325:      *
326:      * @var string
327:      */
328:     protected $_sFunctionName;
329: 
330:     /**
331:      * Callback name.
332:      * Contains either the function name to invoke, or a indexed array
333:      * (class/object and method)
334:      * and it's method to execute.
335:      *
336:      * @var array string
337:      */
338:     protected $_mCallback;
339: 
340:     /**
341:      * Parameter to pass to the function
342:      *
343:      * @var array
344:      */
345:     protected $_aParameters;
346: 
347:     /**
348:      * Temporary arguments holder
349:      *
350:      * @var array null
351:      */
352:     protected $_mTemporaryArguments;
353: 
354:     /**
355:      * Constructor, sets the CEC chain item properties.
356:      *
357:      * @param string $sChainName
358:      * @param string $sFunctionName
359:      * @param array  $aParameters
360:      */
361:     public function __construct($sChainName, $sFunctionName, $aParameters) {
362:         $this->setChainName($sChainName);
363:         $this->setFunctionName($sFunctionName);
364:         $this->setParameters($aParameters);
365:         $this->setCallback($this->getFunctionName());
366:     }
367: 
368:     /**
369:      * Sets the chain name
370:      *
371:      * @param string $sChainName
372:      */
373:     public function setChainName($sChainName) {
374:         $this->_sChainName = $sChainName;
375:     }
376: 
377:     /**
378:      * Returns the chain name
379:      *
380:      * @return string
381:      */
382:     public function getChainName() {
383:         return $this->_sChainName;
384:     }
385: 
386:     /**
387:      * Sets the function name
388:      *
389:      * @param string $sFunctionName
390:      */
391:     public function setFunctionName($sFunctionName) {
392:         $this->_sFunctionName = $sFunctionName;
393:     }
394: 
395:     /**
396:      * Returns the function name
397:      *
398:      * @return string
399:      */
400:     public function getFunctionName() {
401:         return $this->_sFunctionName;
402:     }
403: 
404:     /**
405:      * Sets the callback parameters
406:      *
407:      * @param array $aParameters
408:      */
409:     public function setParameters(array $aParameters) {
410:         $this->_aParameters = $aParameters;
411:     }
412: 
413:     /**
414:      * Returns the function name
415:      *
416:      * @return array
417:      */
418:     public function getParameters() {
419:         return $this->_aParameters;
420:     }
421: 
422:     /**
423:      * Sets the callback
424:      *
425:      * @throws cInvalidArgumentException if the given callback is not a string or an array
426:      * @return string array
427:      */
428:     public function setCallback($callback) {
429:         if (is_string($callback) || is_array($callback)) {
430:             $this->_mCallback = $callback;
431:         } else {
432:             throw new cInvalidArgumentException("Callback has to be a string or an array.");
433:         }
434:     }
435: 
436:     /**
437:      * Returns the callback
438:      *
439:      * @return string array
440:      */
441:     public function getCallback() {
442:         return $this->_mCallback;
443:     }
444: 
445:     /**
446:      * Another way to set the arguments before invoking execute() method.
447:      *
448:      * @param array $args
449:      *
450:      * @return void
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,
459:      * it returns them and resets the property.
460:      *
461:      * @param array $args
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: }
486: