ActiveRecord.php 11.9 KB
Newer Older
1 2 3 4 5 6 7
<?php
/**
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */

8
namespace yii\mongodb;
9 10

use yii\base\InvalidConfigException;
11
use yii\db\BaseActiveRecord;
12 13 14 15 16
use yii\db\StaleObjectException;
use yii\helpers\Inflector;
use yii\helpers\StringHelper;

/**
17
 * ActiveRecord is the base class for classes representing Mongo documents in terms of objects.
18 19 20 21
 *
 * @author Paul Klimov <klimov.paul@gmail.com>
 * @since 2.0
 */
22
abstract class ActiveRecord extends BaseActiveRecord
23 24
{
	/**
25
	 * Returns the Mongo connection used by this AR class.
26
	 * By default, the "mongodb" application component is used as the Mongo connection.
27 28 29 30 31
	 * 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()
	{
32
		return \Yii::$app->getComponent('mongodb');
33 34 35
	}

	/**
36
	 * Updates all documents in the collection using the provided attribute values and conditions.
37 38 39 40 41 42
	 * For example, to change the status to be 1 for all customers whose status is 2:
	 *
	 * ~~~
	 * Customer::updateAll(['status' => 1], ['status' = 2]);
	 * ~~~
	 *
43 44
	 * @param array $attributes attribute values (name-value pairs) to be saved into the collection
	 * @param array $condition description of the objects to update.
45 46
	 * Please refer to [[Query::where()]] on how to specify this parameter.
	 * @param array $options list of options in format: optionName => optionValue.
47
	 * @return integer the number of documents updated.
48 49 50 51 52 53 54
	 */
	public static function updateAll($attributes, $condition = [], $options = [])
	{
		return static::getCollection()->update($condition, $attributes, $options);
	}

	/**
55
	 * Updates all documents in the collection using the provided counter changes and conditions.
56 57 58 59 60 61 62 63
	 * For example, to increment all customers' age by 1,
	 *
	 * ~~~
	 * Customer::updateAllCounters(['age' => 1]);
	 * ~~~
	 *
	 * @param array $counters the counters to be updated (attribute name => increment value).
	 * Use negative values if you want to decrement the counters.
64
	 * @param array $condition description of the objects to update.
65 66
	 * Please refer to [[Query::where()]] on how to specify this parameter.
	 * @param array $options list of options in format: optionName => optionValue.
67
	 * @return integer the number of documents updated.
68 69 70
	 */
	public static function updateAllCounters($counters, $condition = [], $options = [])
	{
71
		return static::getCollection()->update($condition, ['$inc' => $counters], $options);
72 73 74
	}

	/**
75 76
	 * Deletes documents in the collection using the provided conditions.
	 * WARNING: If you do not specify any condition, this method will delete documents rows in the collection.
77 78 79 80 81 82 83
	 *
	 * For example, to delete all customers whose status is 3:
	 *
	 * ~~~
	 * Customer::deleteAll('status = 3');
	 * ~~~
	 *
84
	 * @param array $condition description of the objects to delete.
85 86
	 * Please refer to [[Query::where()]] on how to specify this parameter.
	 * @param array $options list of options in format: optionName => optionValue.
87
	 * @return integer the number of documents deleted.
88 89 90 91 92 93 94 95 96 97 98 99
	 */
	public static function deleteAll($condition = [], $options = [])
	{
		$options['w'] = 1;
		if (!array_key_exists('multiple', $options)) {
			$options['multiple'] = true;
		}
		return static::getCollection()->remove($condition, $options);
	}

	/**
	 * Creates an [[ActiveQuery]] instance.
100
	 * This method is called by [[find()]] to start a "find" command.
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118
	 * 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(['modelClass' => get_called_class()]);
	}

	/**
	 * Declares the name of the Mongo collection associated with this AR class.
	 * Collection name can be either a string or array:
	 *  - if string considered as the name of the collection inside the default database.
	 *  - if array - first element considered as the name of the database, second - as
	 * name of collection inside that database
	 * By default this method returns the class name as the collection name by calling [[Inflector::camel2id()]].
	 * For example, 'Customer' becomes 'customer', and 'OrderItem' becomes
	 * 'order_item'. You may override this method if the table is not named after this convention.
119
	 * @return string|array the collection name
120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138
	 */
	public static function collectionName()
	{
		return Inflector::camel2id(StringHelper::basename(get_called_class()), '_');
	}

	/**
	 * Return the Mongo collection instance for this AR class.
	 * @return Collection collection instance.
	 */
	public static function getCollection()
	{
		return static::getDb()->getCollection(static::collectionName());
	}

	/**
	 * Returns the primary key name(s) for this AR class.
	 * The default implementation will return ['_id'].
	 *
139
	 * Note that an array should be returned even for a collection with single primary key.
140
	 *
141
	 * @return string[] the primary keys of the associated Mongo collection.
142 143 144 145 146 147 148 149 150 151 152 153 154
	 */
	public static function primaryKey()
	{
		return ['_id'];
	}

	/**
	 * Creates an [[ActiveRelation]] instance.
	 * This method is called by [[hasOne()]] and [[hasMany()]] to create a relation instance.
	 * You may override this method to return a customized relation.
	 * @param array $config the configuration passed to the ActiveRelation class.
	 * @return ActiveRelation the newly created [[ActiveRelation]] instance.
	 */
155
	public static function createRelation($config = [])
156 157 158 159 160 161
	{
		return new ActiveRelation($config);
	}

	/**
	 * Returns the list of all attribute names of the model.
162 163 164 165 166 167 168 169 170
	 * This method must be overridden by child classes to define available attributes.
	 * Note: primary key attribute "_id" should be always present in returned array.
	 * For example:
	 * ~~~
	 * public function attributes()
	 * {
	 *     return ['_id', 'name', 'address', 'status'];
	 * }
	 * ~~~
171 172 173 174
	 * @return array list of attribute names.
	 */
	public function attributes()
	{
175
		throw new InvalidConfigException('The attributes() method of mongodb ActiveRecord has to be implemented by child classes.');
176 177 178
	}

	/**
179
	 * Inserts a row into the associated Mongo collection using the attribute values of this record.
180 181 182 183 184 185 186 187
	 *
	 * 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;
188
	 * 4. insert the record into collection. If this fails, it will skip the rest of the steps;
189 190 191 192 193 194 195 196
	 * 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 [[dirtyAttributes|changed attribute values]] will be inserted into database.
	 *
197 198
	 * If the primary key  is null during insertion, it will be populated with the actual
	 * value after insertion.
199 200 201 202 203 204 205 206 207 208 209
	 *
	 * 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.
210
	 * If the validation fails, the record will not be inserted into the collection.
211
	 * @param array $attributes list of attributes that need to be saved. Defaults to null,
212
	 * meaning all attributes that are loaded will be saved.
213 214 215 216 217 218 219 220 221 222 223 224 225 226 227
	 * @return boolean whether the attributes are valid and the record is inserted successfully.
	 * @throws \Exception in case insert failed.
	 */
	public function insert($runValidation = true, $attributes = null)
	{
		if ($runValidation && !$this->validate($attributes)) {
			return false;
		}
		$result = $this->insertInternal($attributes);
		return $result;
	}

	/**
	 * @see ActiveRecord::insert()
	 */
228
	protected function insertInternal($attributes = null)
229 230 231 232 233 234
	{
		if (!$this->beforeSave(true)) {
			return false;
		}
		$values = $this->getDirtyAttributes($attributes);
		if (empty($values)) {
235
			$currentAttributes = $this->getAttributes();
236
			foreach ($this->primaryKey() as $key) {
237
				$values[$key] = isset($currentAttributes[$key]) ? $currentAttributes[$key] : null;
238 239 240 241 242 243
			}
		}
		$collection = static::getCollection();
		$newId = $collection->insert($values);
		$this->setAttribute('_id', $newId);
		foreach ($values as $name => $value) {
244
			$this->setOldAttribute($name, $value);
245 246 247 248 249 250
		}
		$this->afterSave(true);
		return true;
	}

	/**
251
	 * @see ActiveRecord::update()
252 253
	 * @throws StaleObjectException
	 */
254
	protected function updateInternal($attributes = null)
255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273
	{
		if (!$this->beforeSave(false)) {
			return false;
		}
		$values = $this->getDirtyAttributes($attributes);
		if (empty($values)) {
			$this->afterSave(false);
			return 0;
		}
		$condition = $this->getOldPrimaryKey(true);
		$lock = $this->optimisticLock();
		if ($lock !== null) {
			if (!isset($values[$lock])) {
				$values[$lock] = $this->$lock + 1;
			}
			$condition[$lock] = $this->$lock;
		}
		// We do not check the return value of update() because it's possible
		// that it doesn't change anything and thus returns 0.
274
		$rows = static::getCollection()->update($condition, $values);
275 276 277 278 279 280

		if ($lock !== null && !$rows) {
			throw new StaleObjectException('The object being updated is outdated.');
		}

		foreach ($values as $name => $value) {
281
			$this->setOldAttribute($name, $this->getAttribute($name));
282 283 284 285 286 287
		}
		$this->afterSave(false);
		return $rows;
	}

	/**
288
	 * Deletes the document corresponding to this active record from the collection.
289 290 291 292 293
	 *
	 * This method performs the following steps in order:
	 *
	 * 1. call [[beforeDelete()]]. If the method returns false, it will skip the
	 *    rest of the steps;
294
	 * 2. delete the document from the collection;
295 296 297 298 299
	 * 3. call [[afterDelete()]].
	 *
	 * In the above step 1 and 3, events named [[EVENT_BEFORE_DELETE]] and [[EVENT_AFTER_DELETE]]
	 * will be raised by the corresponding methods.
	 *
300 301
	 * @return integer|boolean the number of documents deleted, or false if the deletion is unsuccessful for some reason.
	 * Note that it is possible the number of documents deleted is 0, even though the deletion execution is successful.
302 303 304 305 306 307 308 309
	 * @throws StaleObjectException if [[optimisticLock|optimistic locking]] is enabled and the data
	 * being deleted is outdated.
	 * @throws \Exception in case delete failed.
	 */
	public function delete()
	{
		$result = false;
		if ($this->beforeDelete()) {
310
			$result = $this->deleteInternal();
311 312 313 314 315
			$this->afterDelete();
		}
		return $result;
	}

316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
	/**
	 * @see ActiveRecord::delete()
	 * @throws StaleObjectException
	 */
	protected function deleteInternal()
	{
		// 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
		$condition = $this->getOldPrimaryKey(true);
		$lock = $this->optimisticLock();
		if ($lock !== null) {
			$condition[$lock] = $this->$lock;
		}
		$result = static::getCollection()->remove($condition);
		if ($lock !== null && !$result) {
			throw new StaleObjectException('The object being deleted is outdated.');
		}
		$this->setOldAttributes(null);
		return $result;
	}

337 338 339 340 341
	/**
	 * 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.
	 * If one of the records [[isNewRecord|is new]] they are also considered not equal.
	 * @param ActiveRecord $record record to compare to
342
	 * @return boolean whether the two active records refer to the same row in the same Mongo collection.
343 344 345 346 347 348
	 */
	public function equals($record)
	{
		if ($this->isNewRecord || $record->isNewRecord) {
			return false;
		}
349
		return $this->collectionName() === $record->collectionName() && (string)$this->getPrimaryKey() === (string)$record->getPrimaryKey();
350
	}
351
}