From 76b153a368b39ce1643d87768f72a43b559f2cd1 Mon Sep 17 00:00:00 2001 From: Qiang Xue Date: Sun, 20 Jan 2013 13:37:16 -0500 Subject: [PATCH] fixed event doc. --- docs/api/db/ActiveRecord.md | 18 ++++----- framework/base/Application.php | 4 +- framework/base/Model.php | 85 ++++++++++++++++++++++-------------------- framework/db/ActiveRecord.php | 28 +++++++------- framework/db/Connection.php | 2 +- framework/logging/Logger.php | 2 +- framework/logging/Router.php | 8 ++-- 7 files changed, 77 insertions(+), 70 deletions(-) diff --git a/docs/api/db/ActiveRecord.md b/docs/api/db/ActiveRecord.md index cf4e0b1..945a349 100644 --- a/docs/api/db/ActiveRecord.md +++ b/docs/api/db/ActiveRecord.md @@ -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 diff --git a/framework/base/Application.php b/framework/base/Application.php index 6a20182..55dfeed 100644 --- a/framework/base/Application.php +++ b/framework/base/Application.php @@ -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() { diff --git a/framework/base/Model.php b/framework/base/Model.php index 0dfa915..30cbcfa 100644 --- a/framework/base/Model.php +++ b/framework/base/Model.php @@ -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.', + * ) * ) * ~~~ * diff --git a/framework/db/ActiveRecord.php b/framework/db/ActiveRecord.php index b442c76..e13799b 100644 --- a/framework/db/ActiveRecord.php +++ b/framework/db/ActiveRecord.php @@ -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. */ diff --git a/framework/db/Connection.php b/framework/db/Connection.php index 7b31dc5..3564361 100644 --- a/framework/db/Connection.php +++ b/framework/db/Connection.php @@ -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() { diff --git a/framework/logging/Logger.php b/framework/logging/Logger.php index 2659ea7..b963ea9 100644 --- a/framework/logging/Logger.php +++ b/framework/logging/Logger.php @@ -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) diff --git a/framework/logging/Router.php b/framework/logging/Router.php index 017135f..75fbbc0 100644 --- a/framework/logging/Router.php +++ b/framework/logging/Router.php @@ -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