PageRenderTime 41ms CodeModel.GetById 12ms RepoModel.GetById 1ms app.codeStats 0ms

/yii/framework/base/CComponent.php

https://bitbucket.org/ddonthula/zurmoemail
PHP | 683 lines | 294 code | 30 blank | 359 comment | 53 complexity | b95ea359d4265c34a5a867f7328c97f9 MD5 | raw file
Possible License(s): BSD-3-Clause, LGPL-3.0, LGPL-2.1, BSD-2-Clause, GPL-2.0, GPL-3.0
  1. <?php
  2. /**
  3. * This file contains the foundation classes for component-based and event-driven programming.
  4. *
  5. * @author Qiang Xue <qiang.xue@gmail.com>
  6. * @link http://www.yiiframework.com/
  7. * @copyright Copyright &copy; 2008-2011 Yii Software LLC
  8. * @license http://www.yiiframework.com/license/
  9. */
  10. /**
  11. * CComponent is the base class for all components.
  12. *
  13. * CComponent implements the protocol of defining, using properties and events.
  14. *
  15. * A property is defined by a getter method, and/or a setter method.
  16. * Properties can be accessed in the way like accessing normal object members.
  17. * Reading or writing a property will cause the invocation of the corresponding
  18. * getter or setter method, e.g
  19. * <pre>
  20. * $a=$component->text; // equivalent to $a=$component->getText();
  21. * $component->text='abc'; // equivalent to $component->setText('abc');
  22. * </pre>
  23. * The signatures of getter and setter methods are as follows,
  24. * <pre>
  25. * // getter, defines a readable property 'text'
  26. * public function getText() { ... }
  27. * // setter, defines a writable property 'text' with $value to be set to the property
  28. * public function setText($value) { ... }
  29. * </pre>
  30. *
  31. * An event is defined by the presence of a method whose name starts with 'on'.
  32. * The event name is the method name. When an event is raised, functions
  33. * (called event handlers) attached to the event will be invoked automatically.
  34. *
  35. * An event can be raised by calling {@link raiseEvent} method, upon which
  36. * the attached event handlers will be invoked automatically in the order they
  37. * are attached to the event. Event handlers must have the following signature,
  38. * <pre>
  39. * function eventHandler($event) { ... }
  40. * </pre>
  41. * where $event includes parameters associated with the event.
  42. *
  43. * To attach an event handler to an event, see {@link attachEventHandler}.
  44. * You can also use the following syntax:
  45. * <pre>
  46. * $component->onClick=$callback; // or $component->onClick->add($callback);
  47. * </pre>
  48. * where $callback refers to a valid PHP callback. Below we show some callback examples:
  49. * <pre>
  50. * 'handleOnClick' // handleOnClick() is a global function
  51. * array($object,'handleOnClick') // using $object->handleOnClick()
  52. * array('Page','handleOnClick') // using Page::handleOnClick()
  53. * </pre>
  54. *
  55. * To raise an event, use {@link raiseEvent}. The on-method defining an event is
  56. * commonly written like the following:
  57. * <pre>
  58. * public function onClick($event)
  59. * {
  60. * $this->raiseEvent('onClick',$event);
  61. * }
  62. * </pre>
  63. * where <code>$event</code> is an instance of {@link CEvent} or its child class.
  64. * One can then raise the event by calling the on-method instead of {@link raiseEvent} directly.
  65. *
  66. * Both property names and event names are case-insensitive.
  67. *
  68. * CComponent supports behaviors. A behavior is an
  69. * instance of {@link IBehavior} which is attached to a component. The methods of
  70. * the behavior can be invoked as if they belong to the component. Multiple behaviors
  71. * can be attached to the same component.
  72. *
  73. * To attach a behavior to a component, call {@link attachBehavior}; and to detach the behavior
  74. * from the component, call {@link detachBehavior}.
  75. *
  76. * A behavior can be temporarily enabled or disabled by calling {@link enableBehavior}
  77. * or {@link disableBehavior}, respectively. When disabled, the behavior methods cannot
  78. * be invoked via the component.
  79. *
  80. * Starting from version 1.1.0, a behavior's properties (either its public member variables or
  81. * its properties defined via getters and/or setters) can be accessed through the component it
  82. * is attached to.
  83. *
  84. * @author Qiang Xue <qiang.xue@gmail.com>
  85. * @package system.base
  86. * @since 1.0
  87. */
  88. class CComponent
  89. {
  90. private $_e;
  91. private $_m;
  92. /**
  93. * Returns a property value, an event handler list or a behavior based on its name.
  94. * Do not call this method. This is a PHP magic method that we override
  95. * to allow using the following syntax to read a property or obtain event handlers:
  96. * <pre>
  97. * $value=$component->propertyName;
  98. * $handlers=$component->eventName;
  99. * </pre>
  100. * @param string $name the property name or event name
  101. * @return mixed the property value, event handlers attached to the event, or the named behavior
  102. * @throws CException if the property or event is not defined
  103. * @see __set
  104. */
  105. public function __get($name)
  106. {
  107. $getter='get'.$name;
  108. if(method_exists($this,$getter))
  109. return $this->$getter();
  110. elseif(strncasecmp($name,'on',2)===0 && method_exists($this,$name))
  111. {
  112. // duplicating getEventHandlers() here for performance
  113. $name=strtolower($name);
  114. if(!isset($this->_e[$name]))
  115. $this->_e[$name]=new CList;
  116. return $this->_e[$name];
  117. }
  118. elseif(isset($this->_m[$name]))
  119. return $this->_m[$name];
  120. elseif(is_array($this->_m))
  121. {
  122. foreach($this->_m as $object)
  123. {
  124. if($object->getEnabled() && (property_exists($object,$name) || $object->canGetProperty($name)))
  125. return $object->$name;
  126. }
  127. }
  128. throw new CException(Yii::t('yii','Property "{class}.{property}" is not defined.',
  129. array('{class}'=>get_class($this), '{property}'=>$name)));
  130. }
  131. /**
  132. * Sets value of a component property.
  133. * Do not call this method. This is a PHP magic method that we override
  134. * to allow using the following syntax to set a property or attach an event handler
  135. * <pre>
  136. * $this->propertyName=$value;
  137. * $this->eventName=$callback;
  138. * </pre>
  139. * @param string $name the property name or the event name
  140. * @param mixed $value the property value or callback
  141. * @return mixed
  142. * @throws CException if the property/event is not defined or the property is read only.
  143. * @see __get
  144. */
  145. public function __set($name,$value)
  146. {
  147. $setter='set'.$name;
  148. if(method_exists($this,$setter))
  149. return $this->$setter($value);
  150. elseif(strncasecmp($name,'on',2)===0 && method_exists($this,$name))
  151. {
  152. // duplicating getEventHandlers() here for performance
  153. $name=strtolower($name);
  154. if(!isset($this->_e[$name]))
  155. $this->_e[$name]=new CList;
  156. return $this->_e[$name]->add($value);
  157. }
  158. elseif(is_array($this->_m))
  159. {
  160. foreach($this->_m as $object)
  161. {
  162. if($object->getEnabled() && (property_exists($object,$name) || $object->canSetProperty($name)))
  163. return $object->$name=$value;
  164. }
  165. }
  166. if(method_exists($this,'get'.$name))
  167. throw new CException(Yii::t('yii','Property "{class}.{property}" is read only.',
  168. array('{class}'=>get_class($this), '{property}'=>$name)));
  169. else
  170. throw new CException(Yii::t('yii','Property "{class}.{property}" is not defined.',
  171. array('{class}'=>get_class($this), '{property}'=>$name)));
  172. }
  173. /**
  174. * Checks if a property value is null.
  175. * Do not call this method. This is a PHP magic method that we override
  176. * to allow using isset() to detect if a component property is set or not.
  177. * @param string $name the property name or the event name
  178. * @return boolean
  179. */
  180. public function __isset($name)
  181. {
  182. $getter='get'.$name;
  183. if(method_exists($this,$getter))
  184. return $this->$getter()!==null;
  185. elseif(strncasecmp($name,'on',2)===0 && method_exists($this,$name))
  186. {
  187. $name=strtolower($name);
  188. return isset($this->_e[$name]) && $this->_e[$name]->getCount();
  189. }
  190. elseif(is_array($this->_m))
  191. {
  192. if(isset($this->_m[$name]))
  193. return true;
  194. foreach($this->_m as $object)
  195. {
  196. if($object->getEnabled() && (property_exists($object,$name) || $object->canGetProperty($name)))
  197. return $object->$name!==null;
  198. }
  199. }
  200. return false;
  201. }
  202. /**
  203. * Sets a component property to be null.
  204. * Do not call this method. This is a PHP magic method that we override
  205. * to allow using unset() to set a component property to be null.
  206. * @param string $name the property name or the event name
  207. * @throws CException if the property is read only.
  208. * @return mixed
  209. */
  210. public function __unset($name)
  211. {
  212. $setter='set'.$name;
  213. if(method_exists($this,$setter))
  214. $this->$setter(null);
  215. elseif(strncasecmp($name,'on',2)===0 && method_exists($this,$name))
  216. unset($this->_e[strtolower($name)]);
  217. elseif(is_array($this->_m))
  218. {
  219. if(isset($this->_m[$name]))
  220. $this->detachBehavior($name);
  221. else
  222. {
  223. foreach($this->_m as $object)
  224. {
  225. if($object->getEnabled())
  226. {
  227. if(property_exists($object,$name))
  228. return $object->$name=null;
  229. elseif($object->canSetProperty($name))
  230. return $object->$setter(null);
  231. }
  232. }
  233. }
  234. }
  235. elseif(method_exists($this,'get'.$name))
  236. throw new CException(Yii::t('yii','Property "{class}.{property}" is read only.',
  237. array('{class}'=>get_class($this), '{property}'=>$name)));
  238. }
  239. /**
  240. * Calls the named method which is not a class method.
  241. * Do not call this method. This is a PHP magic method that we override
  242. * to implement the behavior feature.
  243. * @param string $name the method name
  244. * @param array $parameters method parameters
  245. * @return mixed the method return value
  246. */
  247. public function __call($name,$parameters)
  248. {
  249. if($this->_m!==null)
  250. {
  251. foreach($this->_m as $object)
  252. {
  253. if($object->getEnabled() && method_exists($object,$name))
  254. return call_user_func_array(array($object,$name),$parameters);
  255. }
  256. }
  257. if(class_exists('Closure', false) && $this->canGetProperty($name) && $this->$name instanceof Closure)
  258. return call_user_func_array($this->$name, $parameters);
  259. throw new CException(Yii::t('yii','{class} and its behaviors do not have a method or closure named "{name}".',
  260. array('{class}'=>get_class($this), '{name}'=>$name)));
  261. }
  262. /**
  263. * Returns the named behavior object.
  264. * The name 'asa' stands for 'as a'.
  265. * @param string $behavior the behavior name
  266. * @return IBehavior the behavior object, or null if the behavior does not exist
  267. */
  268. public function asa($behavior)
  269. {
  270. return isset($this->_m[$behavior]) ? $this->_m[$behavior] : null;
  271. }
  272. /**
  273. * Attaches a list of behaviors to the component.
  274. * Each behavior is indexed by its name and should be an instance of
  275. * {@link IBehavior}, a string specifying the behavior class, or an
  276. * array of the following structure:
  277. * <pre>
  278. * array(
  279. * 'class'=>'path.to.BehaviorClass',
  280. * 'property1'=>'value1',
  281. * 'property2'=>'value2',
  282. * )
  283. * </pre>
  284. * @param array $behaviors list of behaviors to be attached to the component
  285. */
  286. public function attachBehaviors($behaviors)
  287. {
  288. foreach($behaviors as $name=>$behavior)
  289. $this->attachBehavior($name,$behavior);
  290. }
  291. /**
  292. * Detaches all behaviors from the component.
  293. */
  294. public function detachBehaviors()
  295. {
  296. if($this->_m!==null)
  297. {
  298. foreach($this->_m as $name=>$behavior)
  299. $this->detachBehavior($name);
  300. $this->_m=null;
  301. }
  302. }
  303. /**
  304. * Attaches a behavior to this component.
  305. * This method will create the behavior object based on the given
  306. * configuration. After that, the behavior object will be initialized
  307. * by calling its {@link IBehavior::attach} method.
  308. * @param string $name the behavior's name. It should uniquely identify this behavior.
  309. * @param mixed $behavior the behavior configuration. This is passed as the first
  310. * parameter to {@link YiiBase::createComponent} to create the behavior object.
  311. * @return IBehavior the behavior object
  312. */
  313. public function attachBehavior($name,$behavior)
  314. {
  315. if(!($behavior instanceof IBehavior))
  316. $behavior=Yii::createComponent($behavior);
  317. $behavior->setEnabled(true);
  318. $behavior->attach($this);
  319. return $this->_m[$name]=$behavior;
  320. }
  321. /**
  322. * Detaches a behavior from the component.
  323. * The behavior's {@link IBehavior::detach} method will be invoked.
  324. * @param string $name the behavior's name. It uniquely identifies the behavior.
  325. * @return IBehavior the detached behavior. Null if the behavior does not exist.
  326. */
  327. public function detachBehavior($name)
  328. {
  329. if(isset($this->_m[$name]))
  330. {
  331. $this->_m[$name]->detach($this);
  332. $behavior=$this->_m[$name];
  333. unset($this->_m[$name]);
  334. return $behavior;
  335. }
  336. }
  337. /**
  338. * Enables all behaviors attached to this component.
  339. */
  340. public function enableBehaviors()
  341. {
  342. if($this->_m!==null)
  343. {
  344. foreach($this->_m as $behavior)
  345. $behavior->setEnabled(true);
  346. }
  347. }
  348. /**
  349. * Disables all behaviors attached to this component.
  350. */
  351. public function disableBehaviors()
  352. {
  353. if($this->_m!==null)
  354. {
  355. foreach($this->_m as $behavior)
  356. $behavior->setEnabled(false);
  357. }
  358. }
  359. /**
  360. * Enables an attached behavior.
  361. * A behavior is only effective when it is enabled.
  362. * A behavior is enabled when first attached.
  363. * @param string $name the behavior's name. It uniquely identifies the behavior.
  364. */
  365. public function enableBehavior($name)
  366. {
  367. if(isset($this->_m[$name]))
  368. $this->_m[$name]->setEnabled(true);
  369. }
  370. /**
  371. * Disables an attached behavior.
  372. * A behavior is only effective when it is enabled.
  373. * @param string $name the behavior's name. It uniquely identifies the behavior.
  374. */
  375. public function disableBehavior($name)
  376. {
  377. if(isset($this->_m[$name]))
  378. $this->_m[$name]->setEnabled(false);
  379. }
  380. /**
  381. * Determines whether a property is defined.
  382. * A property is defined if there is a getter or setter method
  383. * defined in the class. Note, property names are case-insensitive.
  384. * @param string $name the property name
  385. * @return boolean whether the property is defined
  386. * @see canGetProperty
  387. * @see canSetProperty
  388. */
  389. public function hasProperty($name)
  390. {
  391. return method_exists($this,'get'.$name) || method_exists($this,'set'.$name);
  392. }
  393. /**
  394. * Determines whether a property can be read.
  395. * A property can be read if the class has a getter method
  396. * for the property name. Note, property name is case-insensitive.
  397. * @param string $name the property name
  398. * @return boolean whether the property can be read
  399. * @see canSetProperty
  400. */
  401. public function canGetProperty($name)
  402. {
  403. return method_exists($this,'get'.$name);
  404. }
  405. /**
  406. * Determines whether a property can be set.
  407. * A property can be written if the class has a setter method
  408. * for the property name. Note, property name is case-insensitive.
  409. * @param string $name the property name
  410. * @return boolean whether the property can be written
  411. * @see canGetProperty
  412. */
  413. public function canSetProperty($name)
  414. {
  415. return method_exists($this,'set'.$name);
  416. }
  417. /**
  418. * Determines whether an event is defined.
  419. * An event is defined if the class has a method named like 'onXXX'.
  420. * Note, event name is case-insensitive.
  421. * @param string $name the event name
  422. * @return boolean whether an event is defined
  423. */
  424. public function hasEvent($name)
  425. {
  426. return !strncasecmp($name,'on',2) && method_exists($this,$name);
  427. }
  428. /**
  429. * Checks whether the named event has attached handlers.
  430. * @param string $name the event name
  431. * @return boolean whether an event has been attached one or several handlers
  432. */
  433. public function hasEventHandler($name)
  434. {
  435. $name=strtolower($name);
  436. return isset($this->_e[$name]) && $this->_e[$name]->getCount()>0;
  437. }
  438. /**
  439. * Returns the list of attached event handlers for an event.
  440. * @param string $name the event name
  441. * @return CList list of attached event handlers for the event
  442. * @throws CException if the event is not defined
  443. */
  444. public function getEventHandlers($name)
  445. {
  446. if($this->hasEvent($name))
  447. {
  448. $name=strtolower($name);
  449. if(!isset($this->_e[$name]))
  450. $this->_e[$name]=new CList;
  451. return $this->_e[$name];
  452. }
  453. else
  454. throw new CException(Yii::t('yii','Event "{class}.{event}" is not defined.',
  455. array('{class}'=>get_class($this), '{event}'=>$name)));
  456. }
  457. /**
  458. * Attaches an event handler to an event.
  459. *
  460. * An event handler must be a valid PHP callback, i.e., a string referring to
  461. * a global function name, or an array containing two elements with
  462. * the first element being an object and the second element a method name
  463. * of the object.
  464. *
  465. * An event handler must be defined with the following signature,
  466. * <pre>
  467. * function handlerName($event) {}
  468. * </pre>
  469. * where $event includes parameters associated with the event.
  470. *
  471. * This is a convenient method of attaching a handler to an event.
  472. * It is equivalent to the following code:
  473. * <pre>
  474. * $component->getEventHandlers($eventName)->add($eventHandler);
  475. * </pre>
  476. *
  477. * Using {@link getEventHandlers}, one can also specify the excution order
  478. * of multiple handlers attaching to the same event. For example:
  479. * <pre>
  480. * $component->getEventHandlers($eventName)->insertAt(0,$eventHandler);
  481. * </pre>
  482. * makes the handler to be invoked first.
  483. *
  484. * @param string $name the event name
  485. * @param callback $handler the event handler
  486. * @throws CException if the event is not defined
  487. * @see detachEventHandler
  488. */
  489. public function attachEventHandler($name,$handler)
  490. {
  491. $this->getEventHandlers($name)->add($handler);
  492. }
  493. /**
  494. * Detaches an existing event handler.
  495. * This method is the opposite of {@link attachEventHandler}.
  496. * @param string $name event name
  497. * @param callback $handler the event handler to be removed
  498. * @return boolean if the detachment process is successful
  499. * @see attachEventHandler
  500. */
  501. public function detachEventHandler($name,$handler)
  502. {
  503. if($this->hasEventHandler($name))
  504. return $this->getEventHandlers($name)->remove($handler)!==false;
  505. else
  506. return false;
  507. }
  508. /**
  509. * Raises an event.
  510. * This method represents the happening of an event. It invokes
  511. * all attached handlers for the event.
  512. * @param string $name the event name
  513. * @param CEvent $event the event parameter
  514. * @throws CException if the event is undefined or an event handler is invalid.
  515. */
  516. public function raiseEvent($name,$event)
  517. {
  518. $name=strtolower($name);
  519. if(isset($this->_e[$name]))
  520. {
  521. foreach($this->_e[$name] as $handler)
  522. {
  523. if(is_string($handler))
  524. call_user_func($handler,$event);
  525. elseif(is_callable($handler,true))
  526. {
  527. if(is_array($handler))
  528. {
  529. // an array: 0 - object, 1 - method name
  530. list($object,$method)=$handler;
  531. if(is_string($object)) // static method call
  532. call_user_func($handler,$event);
  533. elseif(method_exists($object,$method))
  534. $object->$method($event);
  535. else
  536. throw new CException(Yii::t('yii','Event "{class}.{event}" is attached with an invalid handler "{handler}".',
  537. array('{class}'=>get_class($this), '{event}'=>$name, '{handler}'=>$handler[1])));
  538. }
  539. else // PHP 5.3: anonymous function
  540. call_user_func($handler,$event);
  541. }
  542. else
  543. throw new CException(Yii::t('yii','Event "{class}.{event}" is attached with an invalid handler "{handler}".',
  544. array('{class}'=>get_class($this), '{event}'=>$name, '{handler}'=>gettype($handler))));
  545. // stop further handling if param.handled is set true
  546. if(($event instanceof CEvent) && $event->handled)
  547. return;
  548. }
  549. }
  550. elseif(YII_DEBUG && !$this->hasEvent($name))
  551. throw new CException(Yii::t('yii','Event "{class}.{event}" is not defined.',
  552. array('{class}'=>get_class($this), '{event}'=>$name)));
  553. }
  554. /**
  555. * Evaluates a PHP expression or callback under the context of this component.
  556. *
  557. * Valid PHP callback can be class method name in the form of
  558. * array(ClassName/Object, MethodName), or anonymous function (only available in PHP 5.3.0 or above).
  559. *
  560. * If a PHP callback is used, the corresponding function/method signature should be
  561. * <pre>
  562. * function foo($param1, $param2, ..., $component) { ... }
  563. * </pre>
  564. * where the array elements in the second parameter to this method will be passed
  565. * to the callback as $param1, $param2, ...; and the last parameter will be the component itself.
  566. *
  567. * If a PHP expression is used, the second parameter will be "extracted" into PHP variables
  568. * that can be directly accessed in the expression. See {@link http://us.php.net/manual/en/function.extract.php PHP extract}
  569. * for more details. In the expression, the component object can be accessed using $this.
  570. *
  571. * @param mixed $_expression_ a PHP expression or PHP callback to be evaluated.
  572. * @param array $_data_ additional parameters to be passed to the above expression/callback.
  573. * @return mixed the expression result
  574. * @since 1.1.0
  575. */
  576. public function evaluateExpression($_expression_,$_data_=array())
  577. {
  578. if(is_string($_expression_))
  579. {
  580. extract($_data_);
  581. return eval('return '.$_expression_.';');
  582. }
  583. else
  584. {
  585. $_data_[]=$this;
  586. return call_user_func_array($_expression_, $_data_);
  587. }
  588. }
  589. }
  590. /**
  591. * CEvent is the base class for all event classes.
  592. *
  593. * It encapsulates the parameters associated with an event.
  594. * The {@link sender} property describes who raises the event.
  595. * And the {@link handled} property indicates if the event is handled.
  596. * If an event handler sets {@link handled} to true, those handlers
  597. * that are not invoked yet will not be invoked anymore.
  598. *
  599. * @author Qiang Xue <qiang.xue@gmail.com>
  600. * @package system.base
  601. * @since 1.0
  602. */
  603. class CEvent extends CComponent
  604. {
  605. /**
  606. * @var object the sender of this event
  607. */
  608. public $sender;
  609. /**
  610. * @var boolean whether the event is handled. Defaults to false.
  611. * When a handler sets this true, the rest of the uninvoked event handlers will not be invoked anymore.
  612. */
  613. public $handled=false;
  614. /**
  615. * @var mixed additional event parameters.
  616. * @since 1.1.7
  617. */
  618. public $params;
  619. /**
  620. * Constructor.
  621. * @param mixed $sender sender of the event
  622. * @param mixed $params additional parameters for the event
  623. */
  624. public function __construct($sender=null,$params=null)
  625. {
  626. $this->sender=$sender;
  627. $this->params=$params;
  628. }
  629. }
  630. /**
  631. * CEnumerable is the base class for all enumerable types.
  632. *
  633. * To define an enumerable type, extend CEnumberable and define string constants.
  634. * Each constant represents an enumerable value.
  635. * The constant name must be the same as the constant value.
  636. * For example,
  637. * <pre>
  638. * class TextAlign extends CEnumerable
  639. * {
  640. * const Left='Left';
  641. * const Right='Right';
  642. * }
  643. * </pre>
  644. * Then, one can use the enumerable values such as TextAlign::Left and
  645. * TextAlign::Right.
  646. *
  647. * @author Qiang Xue <qiang.xue@gmail.com>
  648. * @package system.base
  649. * @since 1.0
  650. */
  651. class CEnumerable
  652. {
  653. }