Component.php 21.3 KB
Newer Older
Qiang Xue committed
1
<?php
w  
Qiang Xue committed
2 3
/**
 * @link http://www.yiiframework.com/
Qiang Xue committed
4
 * @copyright Copyright (c) 2008 Yii Software LLC
w  
Qiang Xue committed
5 6
 * @license http://www.yiiframework.com/license/
 */
Qiang Xue committed
7 8 9

namespace yii\base;

Qiang Xue committed
10 11
use Yii;

w  
Qiang Xue committed
12
/**
13 14
 * Component is the base class that implements the *property*, *event* and *behavior* features.
 *
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
 * Component provides the *event* and *behavior* features, in addition to the *property* feature which is implemented in
 * its parent class [[Object]].
 *
 * Event is a way to "inject" custom code into existing code at certain places. For example, a comment object can trigger
 * an "add" event when the user adds a comment. We can write custom code and attach it to this event so that when the event
 * is triggered (i.e. comment will be added), our custom code will be executed.
 *
 * An event is identified by a name that should be unique within the class it is defined at. Event names are *case-sensitive*.
 *
 * One or multiple PHP callbacks, called *event handlers*, can be attached to an event. You can call [[trigger()]] to
 * raise an event. When an event is raised, the event handlers will be invoked automatically in the order they were
 * attached.
 *
 * To attach an event handler to an event, call [[on()]]:
 *
 * ~~~
 * $post->on('update', function($event) {
 *     // send email notification
 * });
 * ~~~
 *
 * In the above, an anonymous function is attached to the "update" event of the post. You may attach
 * the following types of event handlers:
 *
 * - anonymous function: `function($event) { ... }`
 * - object method: `[$object, 'handleAdd']`
 * - static class method: `['Page', 'handleAdd']`
 * - global function: `'handleAdd'`
 *
 * The signature of an event handler should be like the following:
 *
 * ~~~
 * function foo($event)
 * ~~~
 *
 * where `$event` is an [[Event]] object which includes parameters associated with the event.
 *
 * You can also attach a handler to an event when configuring a component with a configuration array.
 * The syntax is like the following:
 *
 * ~~~
 * [
 *     'on add' => function($event) { ... }
 * ]
 * ~~~
 *
 * where `on add` stands for attaching an event to the `add` event.
 *
 * Sometimes, you may want to associate extra data with an event handler when you attach it to an event
 * and then access it when the handler is invoked. You may do so by
 *
 * ~~~
 * $post->on('update', function($event) {
 *     // the data can be accessed via $event->data
 * }, $data);
 * ~~~
 *
 *
 * A behavior is an instance of [[Behavior]] or its child class. A component can be attached with one or multiple
 * behaviors. When a behavior is attached to a component, its public properties and methods can be accessed via the
 * component directly, as if the component owns those properties and methods.
 *
 * To attach a behavior to a component, declare it in [[behaviors()]], or explicitly call [[attachBehavior]]. Behaviors
 * declared in [[behaviors()]] are automatically attached to the corresponding component.
 *
 * One can also attach a behavior to a component when configuring it with a configuration array. The syntax is like the
 * following:
 *
 * ~~~
 * [
 *     'as tree' => [
 *         'class' => 'Tree',
 *     ],
 * ]
 * ~~~
 *
 * where `as tree` stands for attaching a behavior named `tree`, and the array will be passed to [[\Yii::createObject()]]
 * to create the behavior object.
93 94 95
 *
 * @property Behavior[] $behaviors List of behaviors attached to this component. This property is read-only.
 *
w  
Qiang Xue committed
96
 * @author Qiang Xue <qiang.xue@gmail.com>
w  
Qiang Xue committed
97
 * @since 2.0
w  
Qiang Xue committed
98
 */
Qiang Xue committed
99
class Component extends Object
Qiang Xue committed
100
{
Qiang Xue committed
101
	/**
Qiang Xue committed
102
	 * @var array the attached event handlers (event name => handlers)
Qiang Xue committed
103
	 */
104
	private $_events = [];
Qiang Xue committed
105 106 107
	/**
	 * @var Behavior[] the attached behaviors (behavior name => behavior)
	 */
Qiang Xue committed
108
	private $_behaviors;
Qiang Xue committed
109 110

	/**
w  
Qiang Xue committed
111 112 113 114 115 116 117 118 119
	 * Returns the value of a component property.
	 * This method will check in the following order and act accordingly:
	 *
	 *  - a property defined by a getter: return the getter result
	 *  - a property of a behavior: return the behavior property value
	 *
	 * Do not call this method directly as it is a PHP magic method that
	 * will be implicitly called when executing `$value = $component->property;`.
	 * @param string $name the property name
120
	 * @return mixed the property value or the value of a behavior's property
Qiang Xue committed
121
	 * @throws UnknownPropertyException if the property is not defined
Qiang Xue committed
122
	 * @throws InvalidCallException if the property is write-only.
123
	 * @see __set()
Qiang Xue committed
124 125 126 127
	 */
	public function __get($name)
	{
		$getter = 'get' . $name;
128 129
		if (method_exists($this, $getter)) {
			// read property, e.g. getName()
Qiang Xue committed
130
			return $this->$getter();
131 132
		} else {
			// behavior property
Qiang Xue committed
133
			$this->ensureBehaviors();
Qiang Xue committed
134
			foreach ($this->_behaviors as $behavior) {
Qiang Xue committed
135
				if ($behavior->canGetProperty($name)) {
Qiang Xue committed
136
					return $behavior->$name;
Qiang Xue committed
137
				}
Qiang Xue committed
138 139
			}
		}
140 141 142 143 144
		if (method_exists($this, 'set' . $name)) {
			throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
		} else {
			throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
		}
Qiang Xue committed
145 146 147
	}

	/**
148
	 * Sets the value of a component property.
w  
Qiang Xue committed
149 150 151
	 * This method will check in the following order and act accordingly:
	 *
	 *  - a property defined by a setter: set the property value
Qiang Xue committed
152 153
	 *  - an event in the format of "on xyz": attach the handler to the event "xyz"
	 *  - a behavior in the format of "as xyz": attach the behavior named as "xyz"
w  
Qiang Xue committed
154 155 156 157
	 *  - a property of a behavior: set the behavior property value
	 *
	 * Do not call this method directly as it is a PHP magic method that
	 * will be implicitly called when executing `$component->property = $value;`.
Qiang Xue committed
158
	 * @param string $name the property name or the event name
w  
Qiang Xue committed
159
	 * @param mixed $value the property value
160 161
	 * @throws UnknownPropertyException if the property is not defined
	 * @throws InvalidCallException if the property is read-only.
162
	 * @see __get()
Qiang Xue committed
163
	 */
Qiang Xue committed
164
	public function __set($name, $value)
Qiang Xue committed
165
	{
Qiang Xue committed
166
		$setter = 'set' . $name;
Qiang Xue committed
167 168
		if (method_exists($this, $setter)) {
			// set property
Qiang Xue committed
169 170
			$this->$setter($value);
			return;
Qiang Xue committed
171 172
		} elseif (strncmp($name, 'on ', 3) === 0) {
			// on event: attach event handler
Qiang Xue committed
173
			$this->on(trim(substr($name, 3)), $value);
Qiang Xue committed
174
			return;
Qiang Xue committed
175 176 177
		} elseif (strncmp($name, 'as ', 3) === 0) {
			// as behavior: attach behavior
			$name = trim(substr($name, 3));
Qiang Xue committed
178
			$this->attachBehavior($name, $value instanceof Behavior ? $value : Yii::createObject($value));
179
			return;
180 181
		} else {
			// behavior property
Qiang Xue committed
182
			$this->ensureBehaviors();
Qiang Xue committed
183
			foreach ($this->_behaviors as $behavior) {
Qiang Xue committed
184
				if ($behavior->canSetProperty($name)) {
Qiang Xue committed
185 186
					$behavior->$name = $value;
					return;
Qiang Xue committed
187
				}
Qiang Xue committed
188 189
			}
		}
Qiang Xue committed
190
		if (method_exists($this, 'get' . $name)) {
Qiang Xue committed
191
			throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
Qiang Xue committed
192
		} else {
Qiang Xue committed
193
			throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
Qiang Xue committed
194
		}
Qiang Xue committed
195 196 197 198
	}

	/**
	 * Checks if a property value is null.
w  
Qiang Xue committed
199 200 201 202 203 204 205
	 * This method will check in the following order and act accordingly:
	 *
	 *  - a property defined by a setter: return whether the property value is null
	 *  - a property of a behavior: return whether the property value is null
	 *
	 * Do not call this method directly as it is a PHP magic method that
	 * will be implicitly called when executing `isset($component->property)`.
Qiang Xue committed
206
	 * @param string $name the property name or the event name
w  
Qiang Xue committed
207
	 * @return boolean whether the named property is null
Qiang Xue committed
208 209 210
	 */
	public function __isset($name)
	{
Qiang Xue committed
211
		$getter = 'get' . $name;
212
		if (method_exists($this, $getter)) {
Qiang Xue committed
213
			return $this->$getter() !== null;
214 215
		} else {
			// behavior property
Qiang Xue committed
216
			$this->ensureBehaviors();
Qiang Xue committed
217
			foreach ($this->_behaviors as $behavior) {
Qiang Xue committed
218
				if ($behavior->canGetProperty($name)) {
Qiang Xue committed
219
					return $behavior->$name !== null;
Qiang Xue committed
220
				}
Qiang Xue committed
221 222 223 224 225 226 227
			}
		}
		return false;
	}

	/**
	 * Sets a component property to be null.
w  
Qiang Xue committed
228 229 230 231 232 233 234 235
	 * This method will check in the following order and act accordingly:
	 *
	 *  - a property defined by a setter: set the property value to be null
	 *  - a property of a behavior: set the property value to be null
	 *
	 * Do not call this method directly as it is a PHP magic method that
	 * will be implicitly called when executing `unset($component->property)`.
	 * @param string $name the property name
236
	 * @throws InvalidCallException if the property is read only.
Qiang Xue committed
237 238 239
	 */
	public function __unset($name)
	{
Qiang Xue committed
240
		$setter = 'set' . $name;
241
		if (method_exists($this, $setter)) {
Qiang Xue committed
242 243
			$this->$setter(null);
			return;
244 245
		} else {
			// behavior property
Qiang Xue committed
246
			$this->ensureBehaviors();
Qiang Xue committed
247
			foreach ($this->_behaviors as $behavior) {
Qiang Xue committed
248
				if ($behavior->canSetProperty($name)) {
Qiang Xue committed
249 250
					$behavior->$name = null;
					return;
Qiang Xue committed
251
				}
Qiang Xue committed
252
			}
Qiang Xue committed
253
		}
254
		throw new InvalidCallException('Unsetting an unknown or read-only property: ' . get_class($this) . '.' . $name);
Qiang Xue committed
255 256 257 258
	}

	/**
	 * Calls the named method which is not a class method.
259 260
	 *
	 * This method will check if any attached behavior has
w  
Qiang Xue committed
261 262 263 264
	 * the named method and will execute it if available.
	 *
	 * Do not call this method directly as it is a PHP magic method that
	 * will be implicitly called when an unknown method is being invoked.
Qiang Xue committed
265
	 * @param string $name the method name
Qiang Xue committed
266
	 * @param array $params method parameters
Qiang Xue committed
267
	 * @return mixed the method return value
Qiang Xue committed
268
	 * @throws UnknownMethodException when calling unknown method
Qiang Xue committed
269
	 */
Qiang Xue committed
270
	public function __call($name, $params)
Qiang Xue committed
271
	{
Qiang Xue committed
272
		$this->ensureBehaviors();
Qiang Xue committed
273
		foreach ($this->_behaviors as $object) {
274
			if ($object->hasMethod($name)) {
Alexander Makarov committed
275
				return call_user_func_array([$object, $name], $params);
w  
Qiang Xue committed
276
			}
Qiang Xue committed
277
		}
Qiang Xue committed
278

Qiang Xue committed
279
		throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
Qiang Xue committed
280 281
	}

Qiang Xue committed
282 283 284 285 286 287
	/**
	 * This method is called after the object is created by cloning an existing one.
	 * It removes all behaviors because they are attached to the old object.
	 */
	public function __clone()
	{
288
		$this->_events = [];
Qiang Xue committed
289
		$this->_behaviors = null;
Qiang Xue committed
290 291
	}

Qiang Xue committed
292 293 294 295 296 297
	/**
	 * Returns a value indicating whether a property is defined for this component.
	 * A property is defined if:
	 *
	 * - the class has a getter or setter method associated with the specified name
	 *   (in this case, property name is case-insensitive);
crtlib committed
298
	 * - the class has a member variable with the specified name (when `$checkVars` is true);
299
	 * - an attached behavior has a property of the given name (when `$checkBehaviors` is true).
Qiang Xue committed
300 301
	 *
	 * @param string $name the property name
crtlib committed
302
	 * @param boolean $checkVars whether to treat member variables as properties
303
	 * @param boolean $checkBehaviors whether to treat behaviors' properties as properties of this component
Qiang Xue committed
304
	 * @return boolean whether the property is defined
305 306
	 * @see canGetProperty()
	 * @see canSetProperty()
Qiang Xue committed
307
	 */
crtlib committed
308
	public function hasProperty($name, $checkVars = true, $checkBehaviors = true)
Qiang Xue committed
309
	{
crtlib committed
310
		return $this->canGetProperty($name, $checkVars, $checkBehaviors) || $this->canSetProperty($name, false, $checkBehaviors);
Qiang Xue committed
311 312 313 314 315 316 317 318
	}

	/**
	 * Returns a value indicating whether a property can be read.
	 * A property can be read if:
	 *
	 * - the class has a getter method associated with the specified name
	 *   (in this case, property name is case-insensitive);
crtlib committed
319
	 * - the class has a member variable with the specified name (when `$checkVars` is true);
320
	 * - an attached behavior has a readable property of the given name (when `$checkBehaviors` is true).
Qiang Xue committed
321 322
	 *
	 * @param string $name the property name
crtlib committed
323
	 * @param boolean $checkVars whether to treat member variables as properties
Qiang Xue committed
324
	 * @param boolean $checkBehaviors whether to treat behaviors' properties as properties of this component
Qiang Xue committed
325
	 * @return boolean whether the property can be read
326
	 * @see canSetProperty()
Qiang Xue committed
327
	 */
crtlib committed
328
	public function canGetProperty($name, $checkVars = true, $checkBehaviors = true)
Qiang Xue committed
329
	{
crtlib committed
330
		if (method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name)) {
Qiang Xue committed
331
			return true;
Qiang Xue committed
332
		} elseif ($checkBehaviors) {
Qiang Xue committed
333
			$this->ensureBehaviors();
Qiang Xue committed
334
			foreach ($this->_behaviors as $behavior) {
crtlib committed
335
				if ($behavior->canGetProperty($name, $checkVars)) {
Qiang Xue committed
336 337 338 339
					return true;
				}
			}
		}
340
		return false;
Qiang Xue committed
341 342 343 344 345 346 347 348
	}

	/**
	 * Returns a value indicating whether a property can be set.
	 * A property can be written if:
	 *
	 * - the class has a setter method associated with the specified name
	 *   (in this case, property name is case-insensitive);
crtlib committed
349
	 * - the class has a member variable with the specified name (when `$checkVars` is true);
350
	 * - an attached behavior has a writable property of the given name (when `$checkBehaviors` is true).
Qiang Xue committed
351 352
	 *
	 * @param string $name the property name
crtlib committed
353
	 * @param boolean $checkVars whether to treat member variables as properties
Qiang Xue committed
354
	 * @param boolean $checkBehaviors whether to treat behaviors' properties as properties of this component
Qiang Xue committed
355
	 * @return boolean whether the property can be written
356
	 * @see canGetProperty()
Qiang Xue committed
357
	 */
crtlib committed
358
	public function canSetProperty($name, $checkVars = true, $checkBehaviors = true)
Qiang Xue committed
359
	{
crtlib committed
360
		if (method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name)) {
Qiang Xue committed
361
			return true;
Qiang Xue committed
362
		} elseif ($checkBehaviors) {
Qiang Xue committed
363
			$this->ensureBehaviors();
Qiang Xue committed
364
			foreach ($this->_behaviors as $behavior) {
crtlib committed
365
				if ($behavior->canSetProperty($name, $checkVars)) {
Qiang Xue committed
366 367 368 369
					return true;
				}
			}
		}
370
		return false;
Qiang Xue committed
371 372
	}

373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398
	/**
	 * Returns a value indicating whether a method is defined.
	 * A method is defined if:
	 *
	 * - the class has a method with the specified name
	 * - an attached behavior has a method with the given name (when `$checkBehaviors` is true).
	 *
	 * @param string $name the property name
	 * @param boolean $checkBehaviors whether to treat behaviors' methods as methods of this component
	 * @return boolean whether the property is defined
	 */
	public function hasMethod($name, $checkBehaviors = true)
	{
		if (method_exists($this, $name)) {
			return true;
		} elseif ($checkBehaviors) {
			$this->ensureBehaviors();
			foreach ($this->_behaviors as $behavior) {
				if ($behavior->hasMethod($name)) {
					return true;
				}
			}
		}
		return false;
	}

Qiang Xue committed
399 400 401 402 403 404 405 406 407 408
	/**
	 * Returns a list of behaviors that this component should behave as.
	 *
	 * Child classes may override this method to specify the behaviors they want to behave as.
	 *
	 * The return value of this method should be an array of behavior objects or configurations
	 * indexed by behavior names. A behavior configuration can be either a string specifying
	 * the behavior class or an array of the following structure:
	 *
	 * ~~~
Alexander Makarov committed
409
	 * 'behaviorName' => [
Qiang Xue committed
410 411 412
	 *     'class' => 'BehaviorClass',
	 *     'property1' => 'value1',
	 *     'property2' => 'value2',
Alexander Makarov committed
413
	 * ]
Qiang Xue committed
414 415
	 * ~~~
	 *
Qiang Xue committed
416 417 418 419
	 * Note that a behavior class must extend from [[Behavior]]. Behavior names can be strings
	 * or integers. If the former, they uniquely identify the behaviors. If the latter, the corresponding
	 * behaviors are anonymous and their properties and methods will NOT be made available via the component
	 * (however, the behaviors can still respond to the component's events).
Qiang Xue committed
420
	 *
Qiang Xue committed
421
	 * Behaviors declared in this method will be attached to the component automatically (on demand).
Qiang Xue committed
422 423 424 425 426
	 *
	 * @return array the behavior configurations.
	 */
	public function behaviors()
	{
Alexander Makarov committed
427
		return [];
Qiang Xue committed
428 429 430
	}

	/**
Qiang Xue committed
431
	 * Returns a value indicating whether there is any handler attached to the named event.
Qiang Xue committed
432
	 * @param string $name the event name
w  
Qiang Xue committed
433
	 * @return boolean whether there is any handler attached to the event.
Qiang Xue committed
434
	 */
w  
Qiang Xue committed
435
	public function hasEventHandlers($name)
Qiang Xue committed
436
	{
Qiang Xue committed
437
		$this->ensureBehaviors();
438
		return !empty($this->_events[$name]) || Event::hasHandlers($this, $name);
Qiang Xue committed
439 440 441 442 443
	}

	/**
	 * Attaches an event handler to an event.
	 *
444
	 * The event handler must be a valid PHP callback. The followings are
w  
Qiang Xue committed
445 446
	 * some examples:
	 *
w  
Qiang Xue committed
447
	 * ~~~
Qiang Xue committed
448
	 * function ($event) { ... }         // anonymous function
Alexander Makarov committed
449 450 451
	 * [$object, 'handleClick']          // $object->handleClick()
	 * ['Page', 'handleClick']           // Page::handleClick()
	 * 'handleClick'                     // global function handleClick()
w  
Qiang Xue committed
452
	 * ~~~
Qiang Xue committed
453
	 *
454
	 * The event handler must be defined with the following signature,
Qiang Xue committed
455
	 *
w  
Qiang Xue committed
456
	 * ~~~
Qiang Xue committed
457
	 * function ($event)
w  
Qiang Xue committed
458
	 * ~~~
Qiang Xue committed
459
	 *
w  
Qiang Xue committed
460
	 * where `$event` is an [[Event]] object which includes parameters associated with the event.
Qiang Xue committed
461 462
	 *
	 * @param string $name the event name
Qiang Xue committed
463 464 465
	 * @param callback $handler the event handler
	 * @param mixed $data the data to be passed to the event handler when the event is triggered.
	 * When the event handler is invoked, this data can be accessed via [[Event::data]].
Qiang Xue committed
466
	 * @see off()
Qiang Xue committed
467
	 */
Qiang Xue committed
468
	public function on($name, $handler, $data = null)
Qiang Xue committed
469
	{
Qiang Xue committed
470
		$this->ensureBehaviors();
Alexander Makarov committed
471
		$this->_events[$name][] = [$handler, $data];
Qiang Xue committed
472 473 474
	}

	/**
Qiang Xue committed
475 476
	 * Detaches an existing event handler from this component.
	 * This method is the opposite of [[on()]].
Qiang Xue committed
477
	 * @param string $name event name
Qiang Xue committed
478 479
	 * @param callback $handler the event handler to be removed.
	 * If it is null, all handlers attached to the named event will be removed.
Qiang Xue committed
480
	 * @return boolean if a handler is found and detached
Qiang Xue committed
481
	 * @see on()
Qiang Xue committed
482
	 */
Qiang Xue committed
483
	public function off($name, $handler = null)
Qiang Xue committed
484
	{
Qiang Xue committed
485
		$this->ensureBehaviors();
Qiang Xue committed
486 487 488 489 490 491 492 493 494 495 496 497
		if (empty($this->_events[$name])) {
			return false;
		}
		if ($handler === null) {
			unset($this->_events[$name]);
			return true;
		} else {
			$removed = false;
			foreach ($this->_events[$name] as $i => $event) {
				if ($event[0] === $handler) {
					unset($this->_events[$name][$i]);
					$removed = true;
Qiang Xue committed
498 499
				}
			}
Qiang Xue committed
500 501 502 503
			if ($removed) {
				$this->_events[$name] = array_values($this->_events[$name]);
			}
			return $removed;
Qiang Xue committed
504
		}
Qiang Xue committed
505 506 507
	}

	/**
Qiang Xue committed
508
	 * Triggers an event.
Qiang Xue committed
509
	 * This method represents the happening of an event. It invokes
Carsten Brandt committed
510
	 * all attached handlers for the event including class-level handlers.
Qiang Xue committed
511
	 * @param string $name the event name
Qiang Xue committed
512
	 * @param Event $event the event parameter. If not set, a default [[Event]] object will be created.
Qiang Xue committed
513
	 */
514
	public function trigger($name, Event $event = null)
Qiang Xue committed
515
	{
Qiang Xue committed
516
		$this->ensureBehaviors();
Qiang Xue committed
517
		if (!empty($this->_events[$name])) {
Qiang Xue committed
518
			if ($event === null) {
Qiang Xue committed
519 520 521 522
				$event = new Event;
			}
			if ($event->sender === null) {
				$event->sender = $this;
Qiang Xue committed
523
			}
Qiang Xue committed
524 525
			$event->handled = false;
			$event->name = $name;
Qiang Xue committed
526 527 528
			foreach ($this->_events[$name] as $handler) {
				$event->data = $handler[1];
				call_user_func($handler[0], $event);
w  
Qiang Xue committed
529
				// stop further handling if the event is handled
Qiang Xue committed
530
				if ($event->handled) {
Qiang Xue committed
531
					return;
w  
Qiang Xue committed
532 533 534
				}
			}
		}
Carsten Brandt committed
535
		// invoke class-level attached handlers
536
		Event::trigger($this, $name, $event);
w  
Qiang Xue committed
537 538 539 540
	}

	/**
	 * Returns the named behavior object.
Qiang Xue committed
541
	 * @param string $name the behavior name
w  
Qiang Xue committed
542 543
	 * @return Behavior the behavior object, or null if the behavior does not exist
	 */
Qiang Xue committed
544
	public function getBehavior($name)
w  
Qiang Xue committed
545
	{
Qiang Xue committed
546
		$this->ensureBehaviors();
Qiang Xue committed
547
		return isset($this->_behaviors[$name]) ? $this->_behaviors[$name] : null;
Qiang Xue committed
548 549 550 551 552 553 554 555 556
	}

	/**
	 * Returns all behaviors attached to this component.
	 * @return Behavior[] list of behaviors attached to this component
	 */
	public function getBehaviors()
	{
		$this->ensureBehaviors();
Qiang Xue committed
557
		return $this->_behaviors;
w  
Qiang Xue committed
558 559 560 561 562 563
	}

	/**
	 * Attaches a behavior to this component.
	 * This method will create the behavior object based on the given
	 * configuration. After that, the behavior object will be attached to
Qiang Xue committed
564
	 * this component by calling the [[Behavior::attach()]] method.
Qiang Xue committed
565
	 * @param string $name the name of the behavior.
Qiang Xue committed
566
	 * @param string|array|Behavior $behavior the behavior configuration. This can be one of the following:
w  
Qiang Xue committed
567 568 569
	 *
	 *  - a [[Behavior]] object
	 *  - a string specifying the behavior class
Qiang Xue committed
570
	 *  - an object configuration array that will be passed to [[Yii::createObject()]] to create the behavior object.
w  
Qiang Xue committed
571 572
	 *
	 * @return Behavior the behavior object
573
	 * @see detachBehavior()
w  
Qiang Xue committed
574 575 576
	 */
	public function attachBehavior($name, $behavior)
	{
Qiang Xue committed
577 578
		$this->ensureBehaviors();
		return $this->attachBehaviorInternal($name, $behavior);
w  
Qiang Xue committed
579 580 581 582 583
	}

	/**
	 * Attaches a list of behaviors to the component.
	 * Each behavior is indexed by its name and should be a [[Behavior]] object,
Qiang Xue committed
584
	 * a string specifying the behavior class, or an configuration array for creating the behavior.
w  
Qiang Xue committed
585
	 * @param array $behaviors list of behaviors to be attached to the component
586
	 * @see attachBehavior()
w  
Qiang Xue committed
587 588 589
	 */
	public function attachBehaviors($behaviors)
	{
Qiang Xue committed
590
		$this->ensureBehaviors();
w  
Qiang Xue committed
591
		foreach ($behaviors as $name => $behavior) {
Qiang Xue committed
592
			$this->attachBehaviorInternal($name, $behavior);
w  
Qiang Xue committed
593 594 595 596 597
		}
	}

	/**
	 * Detaches a behavior from the component.
Qiang Xue committed
598
	 * The behavior's [[Behavior::detach()]] method will be invoked.
w  
Qiang Xue committed
599 600 601 602 603
	 * @param string $name the behavior's name.
	 * @return Behavior the detached behavior. Null if the behavior does not exist.
	 */
	public function detachBehavior($name)
	{
604
		$this->ensureBehaviors();
Qiang Xue committed
605 606 607
		if (isset($this->_behaviors[$name])) {
			$behavior = $this->_behaviors[$name];
			unset($this->_behaviors[$name]);
608
			$behavior->detach();
w  
Qiang Xue committed
609
			return $behavior;
Qiang Xue committed
610 611
		} else {
			return null;
w  
Qiang Xue committed
612 613 614 615 616 617 618 619
		}
	}

	/**
	 * Detaches all behaviors from the component.
	 */
	public function detachBehaviors()
	{
620
		$this->ensureBehaviors();
621 622
		foreach ($this->_behaviors as $name => $behavior) {
			$this->detachBehavior($name);
Qiang Xue committed
623 624 625 626 627 628 629 630
		}
	}

	/**
	 * Makes sure that the behaviors declared in [[behaviors()]] are attached to this component.
	 */
	public function ensureBehaviors()
	{
Qiang Xue committed
631
		if ($this->_behaviors === null) {
Alexander Makarov committed
632
			$this->_behaviors = [];
Qiang Xue committed
633
			foreach ($this->behaviors() as $name => $behavior) {
Qiang Xue committed
634
				$this->attachBehaviorInternal($name, $behavior);
Qiang Xue committed
635
			}
w  
Qiang Xue committed
636 637
		}
	}
Qiang Xue committed
638 639 640

	/**
	 * Attaches a behavior to this component.
Qiang Xue committed
641
	 * @param string $name the name of the behavior.
Qiang Xue committed
642 643 644 645 646 647
	 * @param string|array|Behavior $behavior the behavior to be attached
	 * @return Behavior the attached behavior.
	 */
	private function attachBehaviorInternal($name, $behavior)
	{
		if (!($behavior instanceof Behavior)) {
Qiang Xue committed
648
			$behavior = Yii::createObject($behavior);
Qiang Xue committed
649
		}
Qiang Xue committed
650 651
		if (isset($this->_behaviors[$name])) {
			$this->_behaviors[$name]->detach();
Qiang Xue committed
652
		}
Qiang Xue committed
653
		$behavior->attach($this);
Qiang Xue committed
654
		return $this->_behaviors[$name] = $behavior;
Qiang Xue committed
655
	}
Qiang Xue committed
656
}