Commit 76b153a3 by Qiang Xue

fixed event doc.

parent edc48dc9
......@@ -375,27 +375,27 @@ method overriding and event handling mechanisms.
When instantiating a new ActiveRecord instance, we will have the following life cycles:
1. constructor
2. [[init()]]: will trigger an [[init]] event
2. [[init()]]: will trigger an [[EVENT_INIT]] event
When getting an ActiveRecord instance through the [[find()]] method, we will have the following life cycles:
1. constructor
2. [[init()]]: will trigger an [[init]] event
3. [[afterFind()]]: will trigger an [[afterFind]] event
2. [[init()]]: will trigger an [[EVENT_INIT]] event
3. [[afterFind()]]: will trigger an [[EVENT_AFTER_FIND]] event
When calling [[save()]] to insert or update an ActiveRecord, we will have the following life cycles:
1. [[beforeValidate()]]: will trigger an [[beforeValidate]] event
2. [[beforeSave()]]: will trigger an [[beforeSave]] event
1. [[beforeValidate()]]: will trigger an [[EVENT_BEFORE_VALIDATE]] event
2. [[beforeSave()]]: will trigger an [[EVENT_BEFORE_INSERT]] or [[EVENT_BEFORE_UPDATE]] event
3. perform the actual data insertion or updating
4. [[afterSave()]]: will trigger an [[afterSave]] event
5. [[afterValidate()]]: will trigger an [[afterValidate]] event
4. [[afterSave()]]: will trigger an [[EVENT_AFTER_INSERT]] or [[EVENT_AFTER_UPDATE]] event
5. [[afterValidate()]]: will trigger an [[EVENT_AFTER_VALIDATE]] event
Finally when calling [[delete()]] to delete an ActiveRecord, we will have the following life cycles:
1. [[beforeDelete()]]: will trigger an [[beforeDelete]] event
1. [[beforeDelete()]]: will trigger an [[EVENT_BEFORE_DELETE]] event
2. perform the actual data deletion
3. [[afterDelete()]]: will trigger an [[afterDelete]] event
3. [[afterDelete()]]: will trigger an [[EVENT_AFTER_DELETE]] event
### Scopes
......
......@@ -176,7 +176,7 @@ class Application extends Module
}
/**
* Raises the [[beforeRequest]] event right BEFORE the application processes the request.
* Raises the [[EVENT_BEFORE_REQUEST]] event right BEFORE the application processes the request.
*/
public function beforeRequest()
{
......@@ -184,7 +184,7 @@ class Application extends Module
}
/**
* Raises the [[afterRequest]] event right AFTER the application processes the request.
* Raises the [[EVENT_AFTER_REQUEST]] event right AFTER the application processes the request.
*/
public function afterRequest()
{
......
......@@ -26,8 +26,8 @@ use yii\validators\RequiredValidator;
*
* Model also raises the following events when performing data validation:
*
* - [[beforeValidate]]: an event raised at the beginning of [[validate()]]
* - [[afterValidate]]: an event raised at the end of [[validate()]]
* - [[EVENT_BEFORE_VALIDATE]]: an event raised at the beginning of [[validate()]]
* - [[EVENT_AFTER_VALIDATE]]: an event raised at the end of [[validate()]]
*
* You may directly use Model to store model data, or extend it with customization.
* You may also customize Model by attaching [[ModelBehavior|model behaviors]].
......@@ -53,9 +53,17 @@ class Model extends Component implements \IteratorAggregate, \ArrayAccess
*/
const EVENT_AFTER_VALIDATE = 'afterValidate';
private static $_attributes = array(); // class name => array of attribute names
private $_errors; // attribute name => array of errors
private $_validators; // Vector of validators
/**
* @var array validation errors (attribute name => array of errors)
*/
private $_errors;
/**
* @var Vector vector of validators
*/
private $_validators;
/**
* @var string current scenario
*/
private $_scenario = 'default';
/**
......@@ -68,10 +76,10 @@ class Model extends Component implements \IteratorAggregate, \ArrayAccess
*
* ~~~
* array(
* 'attribute list',
* 'validator type',
* 'on'=>'scenario name',
* ...other parameters...
* 'attribute list',
* 'validator type',
* 'on'=>'scenario name',
* ...other parameters...
* )
* ~~~
*
......@@ -79,37 +87,37 @@ class Model extends Component implements \IteratorAggregate, \ArrayAccess
*
* - attribute list: required, specifies the attributes (separated by commas) to be validated;
* - validator type: required, specifies the validator to be used. It can be the name of a model
* class method, the name of a built-in validator, or a validator class name (or its path alias).
* class method, the name of a built-in validator, or a validator class name (or its path alias).
* - on: optional, specifies the [[scenario|scenarios]] (separated by commas) when the validation
* rule can be applied. If this option is not set, the rule will apply to all scenarios.
* rule can be applied. If this option is not set, the rule will apply to all scenarios.
* - additional name-value pairs can be specified to initialize the corresponding validator properties.
* Please refer to individual validator class API for possible properties.
* Please refer to individual validator class API for possible properties.
*
* A validator can be either an object of a class extending [[\yii\validators\Validator]],
* or a model class method (called *inline validator*) that has the following signature:
* A validator can be either an object of a class extending [[Validator]], or a model class method
* (called *inline validator*) that has the following signature:
*
* ~~~
* // $params refers to validation parameters given in the rule
* function validatorName($attribute, $params)
* ~~~
*
* Yii also provides a set of [[\yii\validators\Validator::builtInValidators|built-in validators]].
* Yii also provides a set of [[Validator::builtInValidators|built-in validators]].
* They each has an alias name which can be used when specifying a validation rule.
*
* Below are some examples:
*
* ~~~
* array(
* // built-in "required" validator
* array('username', 'required'),
* // built-in "length" validator customized with "min" and "max" properties
* array('username', 'length', 'min'=>3, 'max'=>12),
* // built-in "compare" validator that is used in "register" scenario only
* array('password', 'compare', 'compareAttribute'=>'password2', 'on'=>'register'),
* // an inline validator defined via the "authenticate()" method in the model class
* array('password', 'authenticate', 'on'=>'login'),
* // a validator of class "CaptchaValidator"
* array('captcha', 'CaptchaValidator'),
* // built-in "required" validator
* array('username', 'required'),
* // built-in "length" validator customized with "min" and "max" properties
* array('username', 'length', 'min'=>3, 'max'=>12),
* // built-in "compare" validator that is used in "register" scenario only
* array('password', 'compare', 'compareAttribute'=>'password2', 'on'=>'register'),
* // an inline validator defined via the "authenticate()" method in the model class
* array('password', 'authenticate', 'on'=>'login'),
* // a validator of class "CaptchaValidator"
* array('captcha', 'CaptchaValidator'),
* );
* ~~~
*
......@@ -151,8 +159,10 @@ class Model extends Component implements \IteratorAggregate, \ArrayAccess
{
$attributes = array();
foreach ($this->getActiveValidators() as $validator) {
foreach ($validator->attributes as $name) {
$attributes[$name] = true;
if ($validator->isActive('default')) {
foreach ($validator->attributes as $name) {
$attributes[$name] = true;
}
}
}
return array(
......@@ -168,11 +178,6 @@ class Model extends Component implements \IteratorAggregate, \ArrayAccess
*/
public function attributes()
{
$className = get_class($this);
if (isset(self::$_attributes[$className])) {
return self::$_attributes[$className];
}
$class = new \ReflectionClass($this);
$names = array();
foreach ($class->getProperties(\ReflectionProperty::IS_PUBLIC) as $property) {
......@@ -181,7 +186,7 @@ class Model extends Component implements \IteratorAggregate, \ArrayAccess
$names[] = $name;
}
}
return self::$_attributes[$className] = $names;
return $names;
}
/**
......@@ -395,13 +400,13 @@ class Model extends Component implements \IteratorAggregate, \ArrayAccess
*
* ~~~
* array(
* 'username' => array(
* 'Username is required.',
* 'Username must contain only word characters.',
* ),
* 'email' => array(
* 'Email address is invalid.',
* )
* 'username' => array(
* 'Username is required.',
* 'Username must contain only word characters.',
* ),
* 'email' => array(
* 'Email address is invalid.',
* )
* )
* ~~~
*
......
......@@ -608,8 +608,9 @@ class ActiveRecord extends Model
* 4. call [[afterSave()]];
* 5. call [[afterValidate()]] when `$runValidation` is true.
*
* In the above step 1, 2, 4 and 5, events named `beforeValidate`, `beforeInsert`,
* `afterInsert` and `afterValidate` will be raised by the corresponding methods.
* In the above step 1, 2, 4 and 5, events [[EVENT_BEFORE_VALIDATE]],
* [[EVENT_BEFORE_INSERT]], [[EVENT_AFTER_INSERT]] and [[EVENT_AFTER_VALIDATE]]
* will be raised by the corresponding methods.
*
* Only the [[changedAttributes|changed attribute values]] will be inserted into database.
*
......@@ -678,8 +679,9 @@ class ActiveRecord extends Model
* 4. call [[afterSave()]];
* 5. call [[afterValidate()]] when `$runValidation` is true.
*
* In the above step 1, 2, 4 and 5, events named `beforeValidate`, `beforeUpdate`,
* `afterUpdate` and `afterValidate` will be raised by the corresponding methods.
* In the above step 1, 2, 4 and 5, events [[EVENT_BEFORE_VALIDATE]],
* [[EVENT_BEFORE_UPDATE]], [[EVENT_AFTER_UPDATE]] and [[EVENT_AFTER_VALIDATE]]
* will be raised by the corresponding methods.
*
* Only the [[changedAttributes|changed attribute values]] will be saved into database.
*
......@@ -760,7 +762,7 @@ class ActiveRecord extends Model
* 2. delete the record from the database;
* 3. call [[afterDelete()]].
*
* In the above step 1 and 3, events named `beforeDelete` and `afterDelete`
* In the above step 1 and 3, events named [[EVENT_BEFORE_DELETE]] and [[EVENT_AFTER_DELETE]]
* will be raised by the corresponding methods.
*
* @return boolean whether the deletion is successful.
......@@ -791,7 +793,7 @@ class ActiveRecord extends Model
/**
* Initializes the object.
* This method is called at the end of the constructor.
* The default implementation will trigger an [[afterInsert]] event.
* The default implementation will trigger an [[EVENT_INIT]] event.
* If you override this method, make sure you call the parent implementation at the end
* to ensure triggering of the event.
*/
......@@ -803,7 +805,7 @@ class ActiveRecord extends Model
/**
* This method is called when the AR object is created and populated with the query result.
* The default implementation will trigger an [[afterFind]] event.
* The default implementation will trigger an [[EVENT_AFTER_FIND]] event.
* When overriding this method, make sure you call the parent implementation to ensure the
* event is triggered.
*/
......@@ -824,8 +826,8 @@ class ActiveRecord extends Model
/**
* This method is called at the beginning of inserting or updating a record.
* The default implementation will trigger a [[beforeInsert]] event when `$insert` is true,
* or a [[beforeUpdate]] event if `$insert` is false.
* The default implementation will trigger an [[EVENT_BEFORE_INSERT]] event when `$insert` is true,
* or an [[EVENT_BEFORE_UPDATE]] event if `$insert` is false.
* When overriding this method, make sure you call the parent implementation like the following:
*
* ~~~
......@@ -854,8 +856,8 @@ class ActiveRecord extends Model
/**
* This method is called at the end of inserting or updating a record.
* The default implementation will trigger an [[afterInsert]] event when `$insert` is true,
* or an [[afterUpdate]] event if `$insert` is false.
* The default implementation will trigger an [[EVENT_AFTER_INSERT]] event when `$insert` is true,
* or an [[EVENT_AFTER_UPDATE]] event if `$insert` is false.
* When overriding this method, make sure you call the parent implementation so that
* the event is triggered.
* @param boolean $insert whether this method called while inserting a record.
......@@ -868,7 +870,7 @@ class ActiveRecord extends Model
/**
* This method is invoked before deleting a record.
* The default implementation raises the [[beforeDelete]] event.
* The default implementation raises the [[EVENT_BEFORE_DELETE]] event.
* When overriding this method, make sure you call the parent implementation like the following:
*
* ~~~
......@@ -894,7 +896,7 @@ class ActiveRecord extends Model
/**
* This method is invoked after deleting a record.
* The default implementation raises the [[afterDelete]] event.
* The default implementation raises the [[EVENT_AFTER_DELETE]] event.
* You may override this method to do postprocessing after the record is deleted.
* Make sure you call the parent implementation so that the event is raised properly.
*/
......
......@@ -375,7 +375,7 @@ class Connection extends Component
* This method is invoked right after the DB connection is established.
* The default implementation turns on `PDO::ATTR_EMULATE_PREPARES`
* if [[emulatePrepare]] is true, and sets the database [[charset]] if it is not empty.
* It then triggers an [[afterOpen]] event.
* It then triggers an [[EVENT_AFTER_OPEN]] event.
*/
protected function initConnection()
{
......
......@@ -133,7 +133,7 @@ class Logger extends \yii\base\Component
/**
* Flushes log messages from memory to targets.
* This method will trigger a [[flush]] or [[finalFlush]] event depending on the $final value.
* This method will trigger an [[EVENT_FLUSH]] or [[EVENT_FINAL_FLUSH]] event depending on the $final value.
* @param boolean $final whether this is a final call during a request.
*/
public function flush($final = false)
......
......@@ -69,8 +69,8 @@ class Router extends Component
/**
* Initializes this application component.
* This method is invoked when the Router component is created by the application.
* The method attaches the [[processLogs]] method to both the [[Logger::flush]] event
* and the [[\yii\base\Application::afterRequest]] event.
* The method attaches the [[processLogs]] method to both the [[Logger::EVENT_FLUSH]] event
* and the [[Logger::EVENT_FINAL_FLUSH]] event.
*/
public function init()
{
......@@ -88,8 +88,8 @@ class Router extends Component
/**
* Retrieves and processes log messages from the system logger.
* This method mainly serves the event handler to [[Logger::flush]]
* and [[Application::endRequest]] events.
* This method mainly serves the event handler to the [[Logger::EVENT_FLUSH]] event
* and the [[Logger::EVENT_FINAL_FLUSH]] event.
* It will retrieve the available log messages from the [[Yii::getLogger()|system logger]]
* and invoke the registered [[targets|log targets]] to do the actual processing.
* @param \yii\base\Event $event event parameter
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment