Error202
/
yii2-bootstrap
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

Finished AR API.

tags/2.0.0-beta
Qiang Xue 12 years ago
parent
3ca50f3043
commit
cc33a930c9
5 changed files with 584 additions and 205 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 22
      docs/api/db/ActiveRecord-find.md
  2. 10
      docs/api/db/ActiveRecord.md
  3. 137
      framework/db/ActiveQuery.php
  4. 542
      framework/db/ActiveRecord.php
  5. 70
      framework/db/ActiveRelation.php

22
docs/api/db/ActiveRecord-find.md
Unescape View File

@ -0,0 +1,22 @@
Because [[ActiveQuery]] implements a set of query building methods,
additional query conditions can be specified by calling the methods of [[ActiveQuery]].
Below are some examples:
~~~
// find all customers
$customers = Customer::find()->all();
// find all active customers and order them by their age:
$customers = Customer::find()
->where(array('status' => 1))
->orderBy('age')
->all();
// find a single customer whose primary key value is 10
$customer = Customer::find(10);
// the above is equivalent to:
$customer = Customer::find()->where(array('id' => 10))->one();
// find a single customer whose age is 30 and whose status is 1
$customer = Customer::find(array('age' => 30, 'status' => 1));
// the above is equivalent to:
$customer = Customer::find()->where(array('age' => 30, 'status' => 1))->one();
~~~

10
docs/api/db/ActiveRecord.md
Unescape View File

@ -1,9 +1 @@
- `beforeInsert`. Raised before the record is saved.
By setting [[\yii\base\ModelEvent::isValid]] to be false, the normal [[save()]] will be stopped.
- `afterInsert`. Raised after the record is saved.
- `beforeUpdate`. Raised before the record is saved.
By setting [[\yii\base\ModelEvent::isValid]] to be false, the normal [[save()]] will be stopped.
- `afterUpdate`. Raised after the record is saved.
- `beforeDelete`. Raised before the record is deleted.
By setting [[\yii\base\ModelEvent::isValid]] to be false, the normal [[delete()]] process will be stopped.
- `afterDelete`. Raised after the record is deleted.

137
framework/db/ActiveQuery.php
Unescape View File

@ -1,6 +1,6 @@
<?php
/**
* ActiveFinder class file.
* ActiveQuery class file.
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @link http://www.yiiframework.com/
@ -13,10 +13,41 @@ namespace yii\db;
use yii\db\Connection;
use yii\db\Command;
use yii\db\QueryBuilder;
use yii\base\VectorIterator;
use yii\db\Expression;
use yii\db\Exception;
/**
* ActiveQuery represents a DB query associated with an Active Record class.
*
* ActiveQuery instances are usually created by [[ActiveRecord::find()]], [[ActiveRecord::findBySql()]]
* and [[ActiveRecord::count()]].
*
* ActiveQuery mainly provides the following methods to retrieve the query results:
*
* - [[one()]]: returns a single record populated with the first row of data.
* - [[all()]]: returns all records based on the query results.
* - [[value()]]: returns the value of the first column in the first row of the query result.
* - [[exists()]]: returns a value indicating whether the query result has data or not.
*
* Because ActiveQuery extends from [[Query]], one can use query methods, such as [[where()]],
* [[orderBy()]] to customize the query options.
*
* ActiveQuery also provides the following additional query options:
*
* - [[with]]: list of relations that this query should be performed with.
* - [[indexBy]]: the name of the column by which the query result should be indexed.
* - [[asArray]]: whether to return each record as an array.
* - [[scopes]]: list of scopes that should be applied to this query.
*
* These options can be configured using methods of the same name. For example:
*
* ~~~
* $customers = Customer::find()->with('orders')->asArray()->all();
* ~~~
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @since 2.0
*/
class ActiveQuery extends Query
{
/**
@ -28,7 +59,7 @@ class ActiveQuery extends Query
*/
public $with;
/**
* @var string the name of the column by which the query result should be indexed.
* @var string the name of the column by which query results should be indexed by.
* This is only used when the query result is returned as an array when calling [[all()]].
*/
public $indexBy;
@ -47,6 +78,14 @@ class ActiveQuery extends Query
*/
public $sql;
/**
* PHP magic method.
* This method is overridden so that scope methods declared in [[modelClass]]
* can be invoked as methods of ActiveQuery.
* @param string $name
* @param array $params
* @return mixed|ActiveQuery
*/
public function __call($name, $params)
{
if (method_exists($this->modelClass, $name)) {
@ -102,10 +141,10 @@ class ActiveQuery extends Query
}
/**
* Returns a scalar value for this query.
* Returns the query result as a scalar value.
* The value returned will be the first column in the first row of the query results.
* @return string|boolean the value of the first column in the first row of the query result.
* False is returned if there is no value.
* False is returned if the query result is empty.
*/
public function value()
{
@ -113,8 +152,8 @@ class ActiveQuery extends Query
}
/**
* Executes query and returns if matching row exists in the table.
* @return bool if row exists in the table.
* Returns a value indicating whether the query result contains any row of data.
* @return boolean whether the query result contains any row of data.
*/
public function exists()
{
@ -141,14 +180,7 @@ class ActiveQuery extends Query
$this->from = array($tableName);
}
if (!empty($this->scopes)) {
foreach ($this->scopes as $name => $config) {
if (is_integer($name)) {
$modelClass::$config($this);
} else {
array_unshift($config, $this);
call_user_func_array(array($modelClass, $name), $config);
}
}
$this->applyScopes($this->scopes);
}
/** @var $qb QueryBuilder */
$qb = $db->getQueryBuilder();
@ -157,12 +189,39 @@ class ActiveQuery extends Query
return $db->createCommand($this->sql, $this->params);
}
/**
* Sets the [[asArray]] property.
* @param boolean $value whether to return the query results in terms of arrays instead of Active Records.
* @return ActiveQuery the query object itself
*/
public function asArray($value = true)
{
$this->asArray = $value;
return $this;
}
/**
* Specifies the relations with which this query should be performed.
*
* The parameters to this method can be either one or multiple strings, or a single array
* of relation names and the optional callbacks to customize the relations.
*
* The followings are some usage examples:
*
* ~~~
* // find customers together with their orders and country
* Customer::find()->with('orders', 'country')->all();
* // find customers together with their country and orders of status 1
* Customer::find()->with(array(
* 'orders' => function($query) {
* $query->andWhere('status = 1');
* },
* 'country',
* ))->all();
* ~~~
*
* @return ActiveQuery the query object itself
*/
public function with()
{
$this->with = func_get_args();
@ -173,13 +232,39 @@ class ActiveQuery extends Query
return $this;
}
/**
* Sets the [[indexBy]] property.
* @param string $column the name of the column by which the query results should be indexed by.
* @return ActiveQuery the query object itself
*/
public function indexBy($column)
{
$this->indexBy = $column;
return $this;
}
public function scopes($names)
/**
* Specifies the scopes to be applied to this query.
*
* The parameters to this method can be either one or multiple strings, or a single array
* of scopes names and their corresponding customization parameters.
*
* The followings are some usage examples:
*
* ~~~
* // find all active customers
* Customer::find()->scopes('active')->all();
* // find active customers whose age is greater than 30
* Customer::find()->scopes(array(
* 'active',
* 'olderThan' => array(30),
* ))->all();
* // alternatively the above statement can be written as:
* Customer::find()->active()->olderThan(30)->all();
* ~~~
* @return ActiveQuery the query object itself
*/
public function scopes()
{
$this->scopes = func_get_args();
if (isset($this->scopes[0]) && is_array($this->scopes[0])) {
@ -189,7 +274,7 @@ class ActiveQuery extends Query
return $this;
}
protected function createModels($rows)
private function createModels($rows)
{
$models = array();
if ($this->asArray) {
@ -216,7 +301,7 @@ class ActiveQuery extends Query
return $models;
}
protected function populateRelations(&$models, $with)
private function populateRelations(&$models, $with)
{
$primaryModel = new $this->modelClass;
$relations = $this->normalizeRelations($primaryModel, $with);
@ -233,9 +318,8 @@ class ActiveQuery extends Query
* @param ActiveRecord $model
* @param array $with
* @return ActiveRelation[]
* @throws \yii\db\Exception
*/
protected function normalizeRelations($model, $with)
private function normalizeRelations($model, $with)
{
$relations = array();
foreach ($with as $name => $callback) {
@ -268,4 +352,17 @@ class ActiveQuery extends Query
}
return $relations;
}
private function applyScopes($scopes)
{
$modelClass = $this->modelClass;
foreach ($scopes as $name => $config) {
if (is_integer($name)) {
$modelClass::$config($this);
} else {
array_unshift($config, $this);
call_user_func_array(array($modelClass, $name), $config);
}
}
}
}

542
framework/db/ActiveRecord.php
Unescape View File

@ -14,7 +14,6 @@ use yii\base\Model;
use yii\base\ModelEvent;
use yii\base\BadMethodException;
use yii\base\BadParamException;
use yii\db\Exception;
use yii\db\Connection;
use yii\db\TableSchema;
use yii\db\Expression;
@ -25,7 +24,23 @@ use yii\util\StringHelper;
*
* @include @yii/db/ActiveRecord.md
*
* @property array $attributes attribute values indexed by attribute names
* @property Connection $dbConnection the database connection used by this AR class.
* @property TableSchema $tableSchema the schema information of the DB table associated with this AR class.
* @property array $oldAttributes the old attribute values (name-value pairs).
* @property array $dirtyAttributes the changed attribute values (name-value pairs).
* @property boolean $isPrimaryKey whether the record is new and should be inserted when calling [[save()]].
* @property mixed $primaryKey the primary key value.
* @property mixed $oldPrimaryKey the old primary key value.
*
* @event ModelEvent beforeInsert an event that is triggered before inserting a record.
* You may set [[ModelEvent::isValid]] to be false to stop the insertion.
* @event Event afterInsert an event that is triggered before inserting a record.
* @event ModelEvent beforeUpdate an event that is triggered before updating a record.
* You may set [[ModelEvent::isValid]] to be false to stop the update.
* @event Event afterUpdate an event that is triggered before updating a record.
* @event ModelEvent beforeDelete an event that is triggered before deleting a record.
* You may set [[ModelEvent::isValid]] to be false to stop the deletion.
* @event Event afterDelete an event that is triggered after deleting a record.
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @since 2.0
@ -60,39 +75,19 @@ abstract class ActiveRecord extends Model
/**
* Creates an [[ActiveQuery]] instance for query purpose.
*
* Because [[ActiveQuery]] implements a set of query building methods,
* additional query conditions can be specified by calling the methods of [[ActiveQuery]].
*
* Below are some examples:
*
* ~~~
* // find all customers
* $customers = Customer::find()->all();
* // find all active customers and order them by their age:
* $customers = Customer::find()
* ->where(array('status' => 1))
* ->orderBy('age')
* ->all();
* // find a single customer whose primary key value is 10
* $customer = Customer::find(10);
* // the above is equivalent to:
* $customer = Customer::find()->where(array('id' => 10))->one();
* // find a single customer whose age is 30 and whose status is 1
* $customer = Customer::find(array('age' => 30, 'status' => 1));
* // the above is equivalent to:
* $customer = Customer::find()->where(array('age' => 30, 'status' => 1))->one();
* ~~~
* @include @yii/db/ActiveRecord-find.md
*
* @param mixed $q the query parameter. This can be one of the followings:
*
* - a scalar value (integer or string): query by a single primary key value and return the
* corresponding record.
* - an array of name-value pairs: query by a set of column values and return a single record matching them.
* - an array of name-value pairs: query by a set of column values and return a single record matching all of them.
* - null: return a new [[ActiveQuery]] object for further query purpose.
*
* @return ActiveQuery|ActiveRecord|null When `$q` is null, a new [[ActiveQuery]] instance
* is returned; when `$q` is a scalar or an array, an ActiveRecord object matching it will be
* returned, or null will be returned if no match is found.
* returned (null will be returned if there is no matching).
* @see createQuery()
*/
public static function find($q = null)
{
@ -108,13 +103,22 @@ abstract class ActiveRecord extends Model
}
/**
* Creates an [[ActiveQuery]] instance and queries by a given SQL statement.
* Note that because the SQL statement is already specified, calling further
* query methods (such as `where()`, `order()`) on [[ActiveQuery]] will have no effect.
* Methods such as `with()`, `asArray()` can still be called though.
* Creates an [[ActiveQuery]] instance with a given SQL statement.
*
* Note that because the SQL statement is already specified, calling additional
* query modification methods (such as `where()`, `order()`) on the created [[ActiveQuery]]
* instance will have no effect. However, calling `with()`, `asArray()` or `indexBy()` is
* still fine.
*
* Below is an example:
*
* ~~~
* $customers = Customer::findBySql('SELECT * FROM tbl_customer')->all();
* ~~~
*
* @param string $sql the SQL statement to be executed
* @param array $params parameters to be bound to the SQL statement during execution.
* @return ActiveQuery the [[ActiveQuery]] instance
* @return ActiveQuery the newly created [[ActiveQuery]] instance
*/
public static function findBySql($sql, $params = array())
{
@ -124,7 +128,7 @@ abstract class ActiveRecord extends Model
}
/**
* Performs a COUNT query for this AR class.
* Creates a `COUNT` query for this AR class.
*
* Below are some usage examples:
*
@ -140,8 +144,7 @@ abstract class ActiveRecord extends Model
* ~~~
*
* @param string $q the count expression. If null, it means `COUNT(*)`.
*
* @return ActiveQuery the [[ActiveQuery]] instance
* @return ActiveQuery the newly created [[ActiveQuery]] instance
*/
public static function count($q = null)
{
@ -156,8 +159,14 @@ abstract class ActiveRecord extends Model
/**
* Updates the whole table using the provided attribute values and conditions.
* @param array $attributes attribute values to be saved into the table
* @param string|array $condition the conditions that will be put in the WHERE part.
* For example, to change the status to be 1 for all customers whose status is 2:
*
* ~~~
* Customer::updateAll(array('status' => 1), 'status = 2');
* ~~~
*
* @param array $attributes attribute values (name-value pairs) to be saved into the table
* @param string|array $condition the conditions that will be put in the WHERE part of the UPDATE SQL.
* Please refer to [[Query::where()]] on how to specify this parameter.
* @param array $params the parameters (name=>value) to be bound to the query.
* @return integer the number of rows updated
@ -170,11 +179,19 @@ abstract class ActiveRecord extends Model
}
/**
* Updates the whole table using the provided counter values and conditions.
* Updates the whole table using the provided counter changes and conditions.
* For example, to increment all customers' age by 1,
*
* ~~~
* Customer::updateAllCounters(array('age' => 1));
* ~~~
*
* @param array $counters the counters to be updated (attribute name => increment value).
* @param string|array $condition the conditions that will be put in the WHERE part.
* Use negative values if you want to decrement the counters.
* @param string|array $condition the conditions that will be put in the WHERE part of the UPDATE SQL.
* Please refer to [[Query::where()]] on how to specify this parameter.
* @param array $params the parameters (name=>value) to be bound to the query.
* Do not name the parameters as `:bp0`, `:bp1`, etc., because they are used internally by this method.
* @return integer the number of rows updated
*/
public static function updateAllCounters($counters, $condition = '', $params = array())
@ -183,8 +200,8 @@ abstract class ActiveRecord extends Model
$n = 0;
foreach ($counters as $name => $value) {
$quotedName = $db->quoteColumnName($name);
$counters[$name] = new Expression("$quotedName+:cv{$n}");
$params[":cv{$n}"] = $value;
$counters[$name] = new Expression("$quotedName+:bp{$n}");
$params[":bp{$n}"] = $value;
$n++;
}
$command = $db->createCommand();
@ -194,10 +211,18 @@ abstract class ActiveRecord extends Model
/**
* Deletes rows in the table using the provided conditions.
* @param string|array $condition the conditions that will be put in the WHERE part.
* WARNING: If you do not specify any condition, this method will delete ALL rows in the table.
*
* For example, to delete all customers whose status is 3:
*
* ~~~
* Customer::deleteAll('status = 3');
* ~~~
*
* @param string|array $condition the conditions that will be put in the WHERE part of the DELETE SQL.
* Please refer to [[Query::where()]] on how to specify this parameter.
* @param array $params the parameters (name=>value) to be bound to the query.
* @return integer the number of rows updated
* @return integer the number of rows deleted
*/
public static function deleteAll($condition = '', $params = array())
{
@ -207,8 +232,10 @@ abstract class ActiveRecord extends Model
}
/**
* Creates a [[ActiveQuery]] instance.
* This method is called by [[find()]] and [[findBySql()]] to start a SELECT query.
* Creates an [[ActiveQuery]] instance.
* This method is called by [[find()]], [[findBySql()]] and [[count()]] to start a SELECT query.
* You may override this method to return a customized query (e.g. `CustomerQuery` specified
* written for querying `Customer` purpose.)
* @return ActiveQuery the newly created [[ActiveQuery]] instance.
*/
public static function createQuery()
@ -221,8 +248,8 @@ abstract class ActiveRecord extends Model
/**
* Declares the name of the database table associated with this AR class.
* By default this method returns the class name as the table name by calling [[StringHelper::camel2id()]]
* with prefix 'tbl_'. For example, 'Customer' becomes 'tbl_customer', and 'OrderDetail' becomes
* 'tbl_order_detail'. You may override this method if the table is not named after this convention.
* with prefix 'tbl_'. For example, 'Customer' becomes 'tbl_customer', and 'OrderItem' becomes
* 'tbl_order_item'. You may override this method if the table is not named after this convention.
* @return string the table name
*/
public static function tableName()
@ -240,12 +267,16 @@ abstract class ActiveRecord extends Model
}
/**
* Returns the primary keys for this AR class.
* The default implementation will return the primary keys as declared
* Returns the primary key name(s) for this AR class.
* The default implementation will return the primary key(s) as declared
* in the DB table that is associated with this AR class.
*
* If the DB table does not declare any primary key, you should override
* this method to return the attributes that you want to use as primary keys
* for this AR class.
*
* Note that an array should be returned even for a table with single primary key.
*
* @return string[] the primary keys of the associated database table.
*/
public static function primaryKey()
@ -288,7 +319,7 @@ abstract class ActiveRecord extends Model
*/
public function __set($name, $value)
{
if (isset($this->getTableSchema()->columns[$name])) {
if (isset($this->_attributes[$name]) || isset($this->getTableSchema()->columns[$name])) {
$this->_attributes[$name] = $value;
} else {
parent::__set($name, $value);
@ -297,21 +328,16 @@ abstract class ActiveRecord extends Model
/**
* Checks if a property value is null.
* This method overrides the parent implementation by checking
* if the named attribute is null or not.
* This method overrides the parent implementation by checking if the named attribute is null or not.
* @param string $name the property name or the event name
* @return boolean whether the property value is null
*/
public function __isset($name)
{
if (isset($this->getTableSchema()->columns[$name])) {
return isset($this->_related[$name]);
} else {
$t = strtolower($name);
if (isset($this->_related[$t])) {
return true;
}
return parent::__isset($name);
try {
return $this->__get($name) !== null;
} catch (\Exception $e) {
return false;
}
}
@ -339,56 +365,89 @@ abstract class ActiveRecord extends Model
* Declares a `has-one` relation.
* The declaration is returned in terms of an [[ActiveRelation]] instance
* through which the related record can be queried and retrieved back.
*
* A `has-one` relation means that there is at most one related record matching
* the criteria set by this relation, e.g., a customer has one country.
*
* For example, to declare the `country` relation for `Customer` class, we can write
* the following code in the `Customer` class:
*
* ~~~
* public function getCountry()
* {
* return $this->hasOne('Country', array('id' => 'country_id'));
* }
* ~~~
*
* Note that in the above, the 'id' key in the `$link` parameter refers to an attribute name
* in the related class `Country`, while the 'country_id' value refers to an attribute name
* in the current AR class.
*
* Call methods declared in [[ActiveRelation]] to further customize the relation.
*
* @param string $class the class name of the related record
* @param array $link the primary-foreign key constraint. The keys of the array refer to
* the columns in the table associated with the `$class` model, while the values of the
* array refer to the corresponding columns in the table associated with this AR class.
* @param array $properties additional property values that should be used to
* initialize the newly created relation object.
* @return ActiveRelation the relation object.
*/
public function hasOne($class, $link, $properties = array())
public function hasOne($class, $link)
{
if (strpos($class, '\\') === false) {
$primaryClass = get_class($this);
if (($pos = strrpos($primaryClass, '\\')) !== false) {
$class = substr($primaryClass, 0, $pos + 1) . $class;
}
}
$properties['modelClass'] = $class;
$properties['primaryModel'] = $this;
$properties['link'] = $link;
$properties['multiple'] = false;
return new ActiveRelation($properties);
return new ActiveRelation(array(
'modelClass' => $this->getNamespacedClass($class),
'primaryModel' => $this,
'link' => $link,
'multiple' => false,
));
}
/**
* Declares a `has-many` relation.
* The declaration is returned in terms of an [[ActiveRelation]] instance
* through which the related record can be queried and retrieved back.
*
* A `has-many` relation means that there are multiple related records matching
* the criteria set by this relation, e.g., a customer has many orders.
*
* For example, to declare the `orders` relation for `Customer` class, we can write
* the following code in the `Customer` class:
*
* ~~~
* public function getOrders()
* {
* return $this->hasMany('Order', array('customer_id' => 'id'));
* }
* ~~~
*
* Note that in the above, the 'customer_id' key in the `$link` parameter refers to
* an attribute name in the related class `Order`, while the 'id' value refers to
* an attribute name in the current AR class.
*
* @param string $class the class name of the related record
* @param array $link the primary-foreign key constraint. The keys of the array refer to
* the columns in the table associated with the `$class` model, while the values of the
* array refer to the corresponding columns in the table associated with this AR class.
* @param array $properties additional property values that should be used to
* initialize the newly created relation object.
* @return ActiveRelation the relation object.
*/
public function hasMany($class, $link, $properties = array())
public function hasMany($class, $link)
{
$relation = $this->hasOne($class, $link, $properties);
$relation->multiple = true;
return $relation;
return new ActiveRelation(array(
'modelClass' => $this->getNamespacedClass($class),
'primaryModel' => $this,
'link' => $link,
'multiple' => true,
));
}
/**
* @param string $name
* @param mixed $value
* Populates the named relation with the related records.
* Note that this method does not check if the relation exists or not.
* @param string $name the relation name (case-insensitive)
* @param ActiveRecord|array|null the related records to be populated into the relation.
*/
public function populateRelation($name, $value)
public function populateRelation($name, $records)
{
$this->_related[$name] = $value;
$this->_related[strtolower($name)] = $records;
}
/**
@ -426,6 +485,25 @@ abstract class ActiveRecord extends Model
}
/**
* Returns the old attribute values.
* @return array the old attribute values (name-value pairs)
*/
public function getOldAttributes()
{
return $this->_oldAttributes === null ? array() : $this->_oldAttributes;
}
/**
* Sets the old attribute values.
* All existing old attribute values will be discarded.
* @param array $values old attribute values to be set.
*/
public function setOldAttributes($values)
{
$this->_oldAttributes = $values;
}
/**
* Returns the old value of the named attribute.
* If this record is the result of a query and the attribute is not loaded,
* null will be returned.
@ -470,7 +548,7 @@ abstract class ActiveRecord extends Model
* changed recently. If null, [[attributes()]] will be used.
* @return array the changed attribute values (name-value pairs)
*/
public function getChangedAttributes($names = null)
public function getDirtyAttributes($names = null)
{
if ($names === null) {
$names = $this->attributes();
@ -496,18 +574,18 @@ abstract class ActiveRecord extends Model
/**
* Saves the current record.
*
* The record is inserted as a row into the database table if its [[isNewRecord]]
* property is true (usually the case when the record is created using the 'new'
* operator). Otherwise, it will be used to update the corresponding row in the table
* (usually the case if the record is obtained using one of those 'find' methods.)
* This method will call [[insert()]] when [[isNewRecord]] is true, or [[update()]]
* when [[isNewRecord]] is false.
*
* Validation will be performed before saving the record. If the validation fails,
* the record will not be saved. You can call [[getErrors()]] to retrieve the
* validation errors.
* For example, to save a customer record:
*
* ~~~
* $customer = new Customer; // or $customer = Customer::find($id);
* $customer->name = $name;
* $customer->email = $email;
* $customer->save();
* ~~~
*
* If the record is saved via insertion, and if its primary key is auto-incremental
* and is not set before insertion, the primary key will be populated with the
* automatically generated key value.
*
* @param boolean $runValidation whether to perform validation before saving the record.
* If the validation fails, the record will not be saved to database.
@ -517,26 +595,52 @@ abstract class ActiveRecord extends Model
*/
public function save($runValidation = true, $attributes = null)
{
if (!$runValidation || $this->validate($attributes)) {
return $this->getIsNewRecord() ? $this->insert($attributes) : $this->update($attributes);
}
return false;
return $this->getIsNewRecord() ? $this->insert($runValidation, $attributes) : $this->update($runValidation, $attributes);
}
/**
* Inserts a row into the table based on this active record attributes.
* If the table's primary key is auto-incremental and is null before insertion,
* Inserts a row into the associated database table using the attribute values of this record.
*
* This method performs the following steps in order:
*
* 1. call [[beforeValidate()]] when `$runValidation` is true. If validation
* fails, it will skip the rest of the steps;
* 2. call [[beforeSave()]]. If the method returns false, it will skip the
* rest of the steps;
* 3. insert the record into database. If this fails, it will skip the rest of the steps;
* 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.
*
* Only the [[changedAttributes|changed attribute values]] will be inserted into database.
*
* If the table's primary key is auto-incremental and is null during insertion,
* it will be populated with the actual value after insertion.
* Note, validation is not performed in this method. You may call [[validate()]] to perform the validation.
*
* For example, to insert a customer record:
*
* ~~~
* $customer = new Customer;
* $customer->name = $name;
* $customer->email = $email;
* $customer->insert();
* ~~~
*
* @param boolean $runValidation whether to perform validation before saving the record.
* If the validation fails, the record will not be inserted into the database.
* @param array $attributes list of attributes that need to be saved. Defaults to null,
* meaning all attributes that are loaded from DB will be saved.
* @return boolean whether the attributes are valid and the record is inserted successfully.
* @throws Exception if the record is not new
*/
public function insert($attributes = null)
public function insert($runValidation = true, $attributes = null)
{
if ($runValidation && !$this->validate($attributes)) {
return false;
}
if ($this->beforeSave(true)) {
$values = $this->getChangedAttributes($attributes);
$values = $this->getDirtyAttributes($attributes);
if ($values === array()) {
foreach ($this->primaryKey() as $key) {
$values[$key] = isset($this->_attributes[$key]) ? $this->_attributes[$key] : null;
@ -565,18 +669,48 @@ abstract class ActiveRecord extends Model
}
/**
* Updates the row represented by this active record.
* All loaded attributes will be saved to the database.
* Note, validation is not performed in this method. You may call [[validate()]] to perform the validation.
* Saves the changes to this active record into the associated database table.
*
* This method performs the following steps in order:
*
* 1. call [[beforeValidate()]] when `$runValidation` is true. If validation
* fails, it will skip the rest of the steps;
* 2. call [[beforeSave()]]. If the method returns false, it will skip the
* rest of the steps;
* 3. save the record into database. If this fails, it will skip the rest of the steps;
* 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.
*
* Only the [[changedAttributes|changed attribute values]] will be saved into database.
*
* For example, to update a customer record:
*
* ~~~
* $customer = Customer::find($id);
* $customer->name = $name;
* $customer->email = $email;
* $customer->update();
* ~~~
*
* @param boolean $runValidation whether to perform validation before saving the record.
* If the validation fails, the record will not be inserted into the database.
* @param array $attributes list of attributes that need to be saved. Defaults to null,
* meaning all attributes that are loaded from DB will be saved.
* @return boolean whether the update is successful
* @return boolean whether the attributes are valid and the record is updated successfully.
*/
public function update($attributes = null)
public function update($runValidation = true, $attributes = null)
{
if ($runValidation && !$this->validate($attributes)) {
return false;
}
if ($this->beforeSave(false)) {
$values = $this->getChangedAttributes($attributes);
$values = $this->getDirtyAttributes($attributes);
if ($values !== array()) {
// We do not check the return value of updateAll() because it's possible
// that the UPDATE statement doesn't change anything and thus returns 0.
$this->updateAll($values, $this->getOldPrimaryKey(true));
foreach ($values as $name => $value) {
$this->_oldAttributes[$name] = $this->_attributes[$name];
@ -590,51 +724,66 @@ abstract class ActiveRecord extends Model
}
/**
* Saves one or several counter columns for the current AR object.
* Updates one or several counter columns for the current AR object.
* Note that this method differs from [[updateAllCounters()]] in that it only
* saves counters for the current AR object.
*
* An example usage is as follows:
*
* ~~~
* $post = Post::find($id)->one();
* $post = Post::find($id);
* $post->updateCounters(array('view_count' => 1));
* ~~~
*
* Use negative values if you want to decrease the counters.
* @param array $counters the counters to be updated (attribute name => increment value)
* Use negative values if you want to decrement the counters.
* @return boolean whether the saving is successful
* @throws Exception if the record is new or any database error
* @see updateAllCounters()
*/
public function updateCounters($counters)
{
$this->updateAllCounters($counters, $this->getOldPrimaryKey(true));
if ($this->updateAllCounters($counters, $this->getOldPrimaryKey(true)) > 0) {
foreach ($counters as $name => $value) {
$this->_attributes[$name] += $value;
$this->_oldAttributes[$name] = $this->_attributes[$name];
}
return true;
} else {
return false;
}
}
/**
* Deletes the row corresponding to this active record.
* Deletes the table row corresponding to this active record.
*
* This method performs the following steps in order:
*
* 1. call [[beforeDelete()]]. If the method returns false, it will skip the
* rest of the steps;
* 2. delete the record from the database;
* 3. call [[afterDelete()]].
*
* In the above step 1 and 3, events named `beforeDelete` and `afterDelete`
* will be raised by the corresponding methods.
*
* @return boolean whether the deletion is successful.
*/
public function delete()
{
if ($this->beforeDelete()) {
$result = $this->deleteAll($this->getPrimaryKey(true)) > 0;
// we do not check the return value of deleteAll() because it's possible
// the record is already deleted in the database and thus the method will return 0
$this->deleteAll($this->getPrimaryKey(true));
$this->_oldAttributes = null;
$this->afterDelete();
return $result;
return true;
} else {
return false;
}
}
/**
* Returns if the current record is new.
* Returns a value indicating whether the current record is new.
* @return boolean whether the record is new and should be inserted when calling [[save()]].
*/
public function getIsNewRecord()
@ -643,7 +792,7 @@ abstract class ActiveRecord extends Model
}
/**
* Sets if the record is new.
* Sets the value indicating whether the record is new.
* @param boolean $value whether the record is new and should be inserted when calling [[save()]].
* @see getIsNewRecord
*/
@ -652,6 +801,29 @@ abstract class ActiveRecord extends Model
$this->_oldAttributes = $value ? null : $this->_attributes;
}
/**
* 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.
* When overriding this method, make sure you call the parent implementation like the following:
*
* ~~~
* public function beforeSave($insert)
* {
* if (parent::beforeSave($insert)) {
* // ...custom code here...
* return true;
* } else {
* return false;
* }
* }
* ~~~
*
* @param boolean $insert whether this method called while inserting a record.
* If false, it means the method is called while updating a record.
* @return boolean whether the insertion or updating should continue.
* If false, the insertion or updating will be cancelled.
*/
public function beforeSave($insert)
{
$event = new ModelEvent($this);
@ -659,6 +831,15 @@ abstract class ActiveRecord extends Model
return $event->isValid;
}
/**
* 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.
* 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.
* If false, it means the method is called while updating a record.
*/
public function afterSave($insert)
{
$this->trigger($insert ? 'afterInsert' : 'afterUpdate');
@ -666,9 +847,21 @@ abstract class ActiveRecord extends Model
/**
* This method is invoked before deleting a record.
* The default implementation raises the `beforeDelete` event.
* You may override this method to do any preparation work for record deletion.
* Make sure you call the parent implementation so that the event is raised properly.
* The default implementation raises the [[beforeDelete]] event.
* When overriding this method, make sure you call the parent implementation like the following:
*
* ~~~
* public function beforeDelete()
* {
* if (parent::beforeDelete()) {
* // ...custom code here...
* return true;
* } else {
* return false;
* }
* }
* ~~~
*
* @return boolean whether the record should be deleted. Defaults to true.
*/
public function beforeDelete()
@ -680,7 +873,7 @@ abstract class ActiveRecord extends Model
/**
* This method is invoked after deleting a record.
* The default implementation raises the `afterDelete` event.
* The default implementation raises the [[afterDelete]] 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.
*/
@ -692,7 +885,8 @@ abstract class ActiveRecord extends Model
/**
* Repopulates this active record with the latest data.
* @param array $attributes
* @return boolean whether the row still exists in the database. If true, the latest data will be populated to this active record.
* @return boolean whether the row still exists in the database. If true, the latest data
* will be populated to this active record.
*/
public function refresh($attributes = null)
{
@ -714,10 +908,10 @@ abstract class ActiveRecord extends Model
}
/**
* Compares current active record with another one.
* The comparison is made by comparing table name and the primary key values of the two active records.
* Returns a value indicating whether the given active record is the same as the current one.
* The comparison is made by comparing the table names and the primary key values of the two active records.
* @param ActiveRecord $record record to compare to
* @return boolean whether the two active records refer to the same row in the database table.
* @return boolean whether the two active records refer to the same row in the same database table.
*/
public function equals($record)
{
@ -725,12 +919,13 @@ abstract class ActiveRecord extends Model
}
/**
* Returns the primary key value.
* Returns the primary key value(s).
* @param boolean $asArray whether to return the primary key value as an array. If true,
* the return value will be an array with column name as key and column value as value.
* the return value will be an array with column names as keys and column values as values.
* Note that for composite primary keys, an array will always be returned regardless of this parameter value.
* @return mixed the primary key value. An array (column name=>column value) is returned if the primary key is composite.
* If primary key is not defined, null will be returned.
* @return mixed the primary key value. An array (column name=>column value) is returned if the primary key
* is composite or `$asArray` is true. A string is returned otherwise (null will be returned if
* the key value is null).
*/
public function getPrimaryKey($asArray = false)
{
@ -747,15 +942,16 @@ abstract class ActiveRecord extends Model
}
/**
* Returns the old primary key value.
* Returns the old primary key value(s).
* This refers to the primary key value that is populated into the record
* after executing a find method (e.g. find(), findAll()).
* The value remains unchanged even if the primary key attribute is manually assigned with a different value.
* @param boolean $asArray whether to return the primary key value as an array. If true,
* the return value will be an array with column name as key and column value as value.
* If this is false (default), a scalar value will be returned for non-composite primary key.
* @return string|array the old primary key value. An array (column name=>column value) is returned if the primary key is composite.
* If primary key is not defined, null will be returned.
* @return mixed the old primary key value. An array (column name=>column value) is returned if the primary key
* is composite or `$asArray` is true. A string is returned otherwise (null will be returned if
* the key value is null).
*/
public function getOldPrimaryKey($asArray = false)
{
@ -772,7 +968,7 @@ abstract class ActiveRecord extends Model
}
/**
* Creates an active record with the given attributes.
* Creates an active record object using a row of data.
* This method is called by [[ActiveQuery]] to populate the query results
* into Active Records.
* @param array $row attribute values (name => value)
@ -797,11 +993,11 @@ abstract class ActiveRecord extends Model
* Creates an active record instance.
* This method is called by [[create()]].
* You may override this method if the instance being created
* depends the attributes that are to be populated to the record.
* depends on the row data to be populated into the record.
* For example, by creating a record based on the value of a column,
* you may implement the so-called single-table inheritance mapping.
* @param array $row list of attribute values for the active records.
* @return ActiveRecord the active record
* @param array $row row data to be populated into the record.
* @return ActiveRecord the newly created active record
*/
public static function instantiate($row)
{
@ -812,7 +1008,7 @@ abstract class ActiveRecord extends Model
* Returns whether there is an element at the specified offset.
* This method is required by the interface ArrayAccess.
* @param mixed $offset the offset to check on
* @return boolean
* @return boolean whether there is an element at the specified offset.
*/
public function offsetExists($offset)
{
@ -841,9 +1037,23 @@ abstract class ActiveRecord extends Model
}
/**
* @param string $name
* @param ActiveRecord $model
* @param array $extraColumns
* Establishes the relationship between two models.
*
* The relationship is established by setting the foreign key value(s) in one model
* to be the corresponding primary key value(s) in the other model.
* The model with the foreign key will be saved into database without performing validation.
*
* If the relationship involves a pivot table, a new row will be inserted into the
* pivot table which contains the primary key values from both models.
*
* Note that this method requires that the primary key value is not null.
*
* @param string $name the name of the relationship
* @param ActiveRecord $model the model to be linked with the current one.
* @param array $extraColumns additional column values to be saved into the pivot table.
* This parameter is only meaningful for a relationship involving a pivot table
* (i.e., a relation set with `[[ActiveRelation::via()]]` or `[[ActiveRelation::viaTable()]]`.)
* @throws BadParamException if the method is unable to link two models.
*/
public function link($name, $model, $extraColumns = array())
{
@ -879,20 +1089,18 @@ abstract class ActiveRecord extends Model
$p2 = $this->isPrimaryKey(array_values($relation->link));
if ($p1 && $p2) {
if ($this->getIsNewRecord() && $model->getIsNewRecord()) {
throw new Exception('both new');
throw new BadParamException('Unable to link models: both models are newly created.');
} elseif ($this->getIsNewRecord()) {
$this->bindModels(array_flip($relation->link), $this, $model);
} elseif ($model->getIsNewRecord()) {
$this->bindModels($relation->link, $model, $this);
} else {
throw new Exception('both old');
$this->bindModels($relation->link, $model, $this);
}
} elseif ($p1) {
$this->bindModels(array_flip($relation->link), $this, $model);
} elseif ($p2) {
$this->bindModels($relation->link, $model, $this);
} else {
throw new Exception('');
throw new BadParamException('Unable to link models: the link does not involve any primary key.');
}
}
@ -910,11 +1118,16 @@ abstract class ActiveRecord extends Model
}
/**
* @param string $name
* @param ActiveRecord $model
* Destroys the relationship between two models.
*
* The model with the foreign key of the relationship will be deleted if `$delete` is true.
* Otherwise, the foreign key will be set null and the model will be saved without validation.
*
* @param string $name the name of the relationship.
* @param ActiveRecord $model the model to be unlinked from the current one.
* @param boolean $delete whether to delete the model that contains the foreign key.
* If false, the model's foreign key will be set null and saved.
* @throws Exception
* @throws BadParamException if the models cannot be unlinked
*/
public function unlink($name, $model, $delete = true)
{
@ -963,7 +1176,7 @@ abstract class ActiveRecord extends Model
}
$delete ? $this->delete() : $this->save(false);
} else {
throw new Exception('');
throw new BadParamException('Unable to unlink models: the link does not involve any primary key.');
}
}
@ -980,17 +1193,36 @@ abstract class ActiveRecord extends Model
}
/**
* Changes the given class name into a namespaced one.
* If the given class name is already namespaced, no change will be made.
* Otherwise, the class name will be changed to use the same namespace as
* the current AR class.
* @param string $class the class name to be namespaced
* @return string the namespaced class name
*/
protected function getNamespacedClass($class)
{
if (strpos($class, '\\') === false) {
$primaryClass = get_class($this);
if (($pos = strrpos($primaryClass, '\\')) !== false) {
return substr($primaryClass, 0, $pos + 1) . $class;
}
}
return $class;
}
/**
* @param array $link
* @param ActiveRecord $foreignModel
* @param ActiveRecord $primaryModel
* @throws Exception
* @throws BadParamException
*/
private function bindModels($link, $foreignModel, $primaryModel)
{
foreach ($link as $fk => $pk) {
$value = $primaryModel->$pk;
if ($value === null) {
throw new Exception('Primary Key is null');
throw new BadParamException('Unable to link models: the primary key of ' . get_class($primaryModel) . ' is null.');
}
$foreignModel->$fk = $value;
}

70
framework/db/ActiveRelation.php
Unescape View File

@ -12,12 +12,19 @@ namespace yii\db;
use yii\db\Connection;
use yii\db\Command;
use yii\base\BadParamException;
/**
* It is used in three scenarios:
* - eager loading: User::find()->with('posts')->all();
* - lazy loading: $user->posts;
* - lazy loading with query options: $user->posts()->where('status=1')->get();
* ActiveRelation represents a relation between two Active Record classes.
*
* ActiveRelation instances are usually created by calling [[ActiveRecord::hasOne()]] and
* [[ActiveRecord::hasMany()]]. An Active Record class declares a relation by defining
* a getter method which calls one of the above methods and returns the created ActiveRelation object.
*
* A relation is specified by [[link]] which represents the association between columns
* of different tables; and the multiplicity of the relation is indicated by [[multiple]].
*
* If a relation involves a pivot table, it may be specified by [[via()]] or [[viaTable()]] method.
*
* @author Qiang Xue <qiang.xue@gmail.com>
* @since 2.0
@ -42,15 +49,17 @@ class ActiveRelation extends ActiveQuery
*/
public $link;
/**
* @var array|ActiveRelation
* @var array|ActiveRelation the query associated with the pivot table. Please call [[via()]]
* or [[viaTable()]] to set this property instead of directly setting it.
*/
public $via;
/**
* @param string $relationName
* @param callback $callback
* @return ActiveRelation
* @throws Exception
* Specifies the relation associated with the pivot table.
* @param string $relationName the relation name. This refers to a relation declared in [[primaryModel]].
* @param callback $callback a PHP callback for customizing the relation associated with the pivot table.
* Its signature should be `function($query)`, where `$query` is the query to be customized.
* @return ActiveRelation the relation object itself.
*/
public function via($relationName, $callback = null)
{
@ -63,9 +72,13 @@ class ActiveRelation extends ActiveQuery
}
/**
* @param string $tableName
* @param array $link
* @param callback $callback
* Specifies the pivot table.
* @param string $tableName the name of the pivot table.
* @param array $link the link between the pivot table and the table associated with [[primaryModel]].
* The keys of the array represent the columns in the pivot table, and the values represent the columns
* in the [[primaryModel]] table.
* @param callback $callback a PHP callback for customizing the relation associated with the pivot table.
* Its signature should be `function($query)`, where `$query` is the query to be customized.
* @return ActiveRelation
*/
public function viaTable($tableName, $link, $callback = null)
@ -118,10 +131,18 @@ class ActiveRelation extends ActiveQuery
return parent::createCommand($db);
}
/**
* Finds the related records and populates them into the primary models.
* This method is internally by [[ActiveQuery]]. Do not call it directly.
* @param string $name the relation name
* @param array $primaryModels primary models
* @return array the related models
* @throws BadParamException
*/
public function findWith($name, &$primaryModels)
{
if (!is_array($this->link)) {
throw new \yii\base\Exception('invalid link');
throw new BadParamException('Invalid link: it must be an array of key-value pairs.');
}
if ($this->via instanceof self) {
@ -173,7 +194,14 @@ class ActiveRelation extends ActiveQuery
}
}
protected function buildBuckets($models, $link, $viaModels = null, $viaLink = null)
/**
* @param array $models
* @param array $link
* @param array $viaModels
* @param array $viaLink
* @return array
*/
private function buildBuckets($models, $link, $viaModels = null, $viaLink = null)
{
$buckets = array();
$linkKeys = array_keys($link);
@ -214,7 +242,12 @@ class ActiveRelation extends ActiveQuery
return $buckets;
}
protected function getModelKey($model, $attributes)
/**
* @param ActiveRecord|array $model
* @param array $attributes
* @return string
*/
private function getModelKey($model, $attributes)
{
if (count($attributes) > 1) {
$key = array();
@ -228,7 +261,10 @@ class ActiveRelation extends ActiveQuery
}
}
protected function filterByModels($models)
/**
* @param array $models
*/
private function filterByModels($models)
{
$attributes = array_keys($this->link);
$values = array();
@ -255,7 +291,7 @@ class ActiveRelation extends ActiveQuery
* @param ActiveRecord[] $primaryModels
* @return array
*/
protected function findPivotRows($primaryModels)
private function findPivotRows($primaryModels)
{
if (empty($primaryModels)) {
return array();

Write Preview
Loading…
Cancel
Save