* @link http://www.yiiframework.com/ * @copyright Copyright © 2008 Yii Software LLC * @license http://www.yiiframework.com/license/ */ namespace yii\redis; use yii\base\InvalidCallException; use yii\base\InvalidConfigException; use yii\base\InvalidParamException; use yii\base\NotSupportedException; use yii\base\UnknownMethodException; use yii\db\TableSchema; use yii\helpers\StringHelper; /** * ActiveRecord is the base class for classes representing relational data in terms of objects. * * @author Carsten Brandt * @since 2.0 */ abstract class ActiveRecord extends \yii\db\ActiveRecord { /** * @var array cache for TableSchema instances */ private static $_tables = array(); /** * Returns the database connection used by this AR class. * By default, the "redis" application component is used as the database connection. * You may override this method if you want to use a different database connection. * @return Connection the database connection used by this AR class. */ public static function getDb() { return \Yii::$app->redis; } /** * @inheritdoc */ public static function findBySql($sql, $params = array()) { throw new NotSupportedException('findBySql() is not supported by redis ActiveRecord'); } /** * 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() { return new ActiveQuery(array( 'modelClass' => get_called_class(), )); } /** * Declares the name of the database table associated with this AR class. * @return string the table name */ public static function tableName() { return static::getTableSchema()->name; } /** * This method is ment to be overridden in redis ActiveRecord subclasses to return a [[RecordSchema]] instance. * @return RecordSchema * @throws \yii\base\InvalidConfigException */ public static function getRecordSchema() { throw new InvalidConfigException(__CLASS__.'::getRecordSchema() needs to be overridden in subclasses and return a RecordSchema.'); } /** * Returns the schema information of the DB table associated with this AR class. * @return TableSchema the schema information of the DB table associated with this AR class. */ public static function getTableSchema() { $class = get_called_class(); if (isset(self::$_tables[$class])) { return self::$_tables[$class]; } return self::$_tables[$class] = static::getRecordSchema(); } /** * 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 [[afterValidate()]] when `$runValidation` is true. * 3. call [[beforeSave()]]. If the method returns false, it will skip the * rest of the steps; * 4. insert the record into database. If this fails, it will skip the rest of the steps; * 5. call [[afterSave()]]; * * In the above step 1, 2, 3 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. * * If the table's primary key is auto-incremental and is null during insertion, * it will be populated with the actual value after insertion. * * 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. */ public function insert($runValidation = true, $attributes = null) { if ($runValidation && !$this->validate($attributes)) { return false; } if ($this->beforeSave(true)) { $db = static::getDb(); $values = $this->getDirtyAttributes($attributes); $pk = array(); // if ($values === array()) { foreach ($this->primaryKey() as $key) { $pk[$key] = $values[$key] = $this->getAttribute($key); if ($pk[$key] === null) { $pk[$key] = $values[$key] = $db->executeCommand('INCR', array(static::tableName() . ':s:' . $key)); $this->setAttribute($key, $values[$key]); } } // } // save pk in a findall pool $db->executeCommand('RPUSH', array(static::tableName(), static::buildKey($pk))); $key = static::tableName() . ':a:' . static::buildKey($pk); // save attributes $args = array($key); foreach($values as $attribute => $value) { $args[] = $attribute; $args[] = $value; } $db->executeCommand('HMSET', $args); $this->setOldAttributes($values); $this->afterSave(true); return true; } return false; } /** * Updates the whole table using the provided attribute values and conditions. * For example, to change the status to be 1 for all customers whose status is 2: * * ~~~ * Customer::updateAll(array('status' => 1), array('id' => 2)); * ~~~ * * @param array $attributes attribute values (name-value pairs) to be saved into the table * @param array $condition the conditions that will be put in the WHERE part of the UPDATE SQL. * Please refer to [[ActiveQuery::where()]] on how to specify this parameter. * @param array $params this parameter is ignored in redis implementation. * @return integer the number of rows updated */ public static function updateAll($attributes, $condition = null, $params = array()) { $db = static::getDb(); if (empty($attributes)) { return 0; } $n=0; foreach(static::fetchPks($condition) as $pk) { $newPk = $pk; $pk = static::buildKey($pk); $key = static::tableName() . ':a:' . $pk; // save attributes $args = array($key); foreach($attributes as $attribute => $value) { if (isset($newPk[$attribute])) { $newPk[$attribute] = $value; } $args[] = $attribute; $args[] = $value; } $newPk = static::buildKey($newPk); $newKey = static::tableName() . ':a:' . $newPk; $db->executeCommand('HMSET', $args); // rename index if ($newPk != $pk) { // TODO make this atomic $db->executeCommand('LINSERT', array(static::tableName(), 'AFTER', $pk, $newPk)); $db->executeCommand('LREM', array(static::tableName(), 0, $pk)); $db->executeCommand('RENAME', array($key, $newKey)); } $n++; } return $n; } /** * 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). * Use negative values if you want to decrement the counters. * @param array $condition the conditions that will be put in the WHERE part of the UPDATE SQL. * Please refer to [[ActiveQuery::where()]] on how to specify this parameter. * @param array $params this parameter is ignored in redis implementation. * @return integer the number of rows updated */ public static function updateAllCounters($counters, $condition = null, $params = array()) { $db = static::getDb(); $n=0; foreach(static::fetchPks($condition) as $pk) { $key = static::tableName() . ':a:' . static::buildKey($pk); foreach($counters as $attribute => $value) { $db->executeCommand('HINCRBY', array($key, $attribute, $value)); } $n++; } return $n; } /** * Deletes rows in the table using the provided conditions. * 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 array $condition the conditions that will be put in the WHERE part of the DELETE SQL. * Please refer to [[ActiveQuery::where()]] on how to specify this parameter. * @param array $params this parameter is ignored in redis implementation. * @return integer the number of rows deleted */ public static function deleteAll($condition = null, $params = array()) { $db = static::getDb(); $attributeKeys = array(); foreach(static::fetchPks($condition) as $pk) { $pk = static::buildKey($pk); $db->executeCommand('LREM', array(static::tableName(), 0, $pk)); $attributeKeys[] = static::tableName() . ':a:' . $pk; } if (empty($attributeKeys)) { return 0; } return $db->executeCommand('DEL', $attributeKeys);// TODO make this atomic or document as NOT } private static function fetchPks($condition) { $query = static::createQuery(); $query->where($condition); $records = $query->asArray()->all(); // TODO limit fetched columns to pk $primaryKey = static::primaryKey(); $pks = array(); foreach($records as $record) { $pk = array(); foreach($primaryKey as $key) { $pk[$key] = $record[$key]; } $pks[] = $pk; } return $pks; } /** * Builds a normalized key from a given primary key value. * * @param mixed $key the key to be normalized * @return string the generated key */ public static function buildKey($key) { if (is_numeric($key)) { return $key; } elseif (is_string($key)) { return ctype_alnum($key) && StringHelper::strlen($key) <= 32 ? $key : md5($key); } elseif (is_array($key)) { if (count($key) == 1) { return self::buildKey(reset($key)); } $isNumeric = true; foreach($key as $value) { if (!is_numeric($value)) { $isNumeric = false; } } if ($isNumeric) { return implode('-', $key); } } return md5(json_encode($key)); } /** * 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. * @return ActiveRelation the relation object. */ public function hasOne($class, $link) { 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. * @return ActiveRelation the relation object. */ public function hasMany($class, $link) { return new ActiveRelation(array( 'modelClass' => $this->getNamespacedClass($class), 'primaryModel' => $this, 'link' => $link, 'multiple' => true, )); } /** * Returns the relation object with the specified name. * A relation is defined by a getter method which returns an [[ActiveRelation]] object. * It can be declared in either the Active Record class itself or one of its behaviors. * @param string $name the relation name * @return ActiveRelation the relation object * @throws InvalidParamException if the named relation does not exist. */ public function getRelation($name) { $getter = 'get' . $name; try { $relation = $this->$getter(); if ($relation instanceof ActiveRelation) { return $relation; } } catch (UnknownMethodException $e) { } throw new InvalidParamException(get_class($this) . ' has no relation named "' . $name . '".'); } /** * 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 InvalidCallException if the method is unable to link two models. */ public function link($name, $model, $extraColumns = array()) { $relation = $this->getRelation($name); if ($relation->via !== null) { // TODO } else { $p1 = $model->isPrimaryKey(array_keys($relation->link)); $p2 = $this->isPrimaryKey(array_values($relation->link)); if ($p1 && $p2) { if ($this->getIsNewRecord() && $model->getIsNewRecord()) { throw new InvalidCallException('Unable to link models: both models are newly created.'); } elseif ($this->getIsNewRecord()) { $this->bindModels(array_flip($relation->link), $this, $model); } else { $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 InvalidCallException('Unable to link models: the link does not involve any primary key.'); } } // update lazily loaded related objects if (!$relation->multiple) { $this->_related[$name] = $model; } elseif (isset($this->_related[$name])) { if ($relation->indexBy !== null) { $indexBy = $relation->indexBy; $this->_related[$name][$model->$indexBy] = $model; } else { $this->_related[$name][] = $model; } } } /** * @param array $link * @param ActiveRecord $foreignModel * @param ActiveRecord $primaryModel * @throws InvalidCallException */ private function bindModels($link, $foreignModel, $primaryModel) { foreach ($link as $fk => $pk) { $value = $primaryModel->$pk; if ($value === null) { throw new InvalidCallException('Unable to link models: the primary key of ' . get_class($primaryModel) . ' is null.'); } $foreignModel->$fk = $value; } $foreignModel->save(false); } /** * 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. * If true, the model containing the foreign key will be deleted. * @throws InvalidCallException if the models cannot be unlinked */ public function unlink($name, $model, $delete = false) { // TODO $relation = $this->getRelation($name); if ($relation->via !== null) { if (is_array($relation->via)) { /** @var $viaRelation ActiveRelation */ list($viaName, $viaRelation) = $relation->via; /** @var $viaClass ActiveRecord */ $viaClass = $viaRelation->modelClass; $viaTable = $viaClass::tableName(); unset($this->_related[strtolower($viaName)]); } else { $viaRelation = $relation->via; $viaTable = reset($relation->via->from); } $columns = array(); foreach ($viaRelation->link as $a => $b) { $columns[$a] = $this->$b; } foreach ($relation->link as $a => $b) { $columns[$b] = $model->$a; } $command = static::getDb()->createCommand(); if ($delete) { $command->delete($viaTable, $columns)->execute(); } else { $nulls = array(); foreach (array_keys($columns) as $a) { $nulls[$a] = null; } $command->update($viaTable, $nulls, $columns)->execute(); } } else { $p1 = $model->isPrimaryKey(array_keys($relation->link)); $p2 = $this->isPrimaryKey(array_values($relation->link)); if ($p1 && $p2 || $p2) { foreach ($relation->link as $a => $b) { $model->$a = null; } $delete ? $model->delete() : $model->save(false); } elseif ($p1) { foreach ($relation->link as $b) { $this->$b = null; } $delete ? $this->delete() : $this->save(false); } else { throw new InvalidCallException('Unable to unlink models: the link does not involve any primary key.'); } } if (!$relation->multiple) { unset($this->_related[$name]); } elseif (isset($this->_related[$name])) { /** @var $b ActiveRecord */ foreach ($this->_related[$name] as $a => $b) { if ($model->getPrimaryKey() == $b->getPrimaryKey()) { unset($this->_related[$name][$a]); } } } } /** * TODO duplicate code, refactor * @param array $keys * @return boolean */ private function isPrimaryKey($keys) { $pks = $this->primaryKey(); foreach ($keys as $key) { if (!in_array($key, $pks, true)) { return false; } } return true; } // TODO implement link and unlink }