ActiveRecord.php 13.5 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 26 27 28 29 30 31 32 33
    /**
     * Returns the Mongo connection used by this AR class.
     * By default, the "mongodb" application component is used as the Mongo 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->getComponent('mongodb');
    }
34

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

54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
    /**
     * Updates all documents in the collection using the provided counter changes and conditions.
     * 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.
     * @param  array   $condition description of the objects to update.
     *                            Please refer to [[Query::where()]] on how to specify this parameter.
     * @param  array   $options   list of options in format: optionName => optionValue.
     * @return integer the number of documents updated.
     */
    public static function updateAllCounters($counters, $condition = [], $options = [])
    {
        return static::getCollection()->update($condition, ['$inc' => $counters], $options);
    }
73

74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
    /**
     * 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.
     *
     * For example, to delete all customers whose status is 3:
     *
     * ~~~
     * Customer::deleteAll(['status' => 3]);
     * ~~~
     *
     * @param  array   $condition description of the objects to delete.
     *                            Please refer to [[Query::where()]] on how to specify this parameter.
     * @param  array   $options   list of options in format: optionName => optionValue.
     * @return integer the number of documents deleted.
     */
    public static function deleteAll($condition = [], $options = [])
    {
        return static::getCollection()->remove($condition, $options);
    }
93

94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
    /**
     * Creates an [[ActiveQuery]] instance.
     *
     * This method is called by [[find()]], [[findBySql()]] to start a SELECT query but also
     * by [[hasOne()]] and [[hasMany()]] to create a relational query.
     * You may override this method to return a customized query (e.g. `CustomerQuery` specified
     * written for querying `Customer` purpose.)
     *
     * You may also define default conditions that should apply to all queries unless overridden:
     *
     * ```php
     * public static function createQuery($config = [])
     * {
     *     return parent::createQuery($config)->where(['deleted' => false]);
     * }
     * ```
     *
     * Note that all queries should use [[Query::andWhere()]] and [[Query::orWhere()]] to keep the
     * default condition. Using [[Query::where()]] will override the default condition.
     *
     * @param  array       $config the configuration passed to the ActiveQuery class.
     * @return ActiveQuery the newly created [[ActiveQuery]] instance.
     */
    public static function createQuery($config = [])
    {
        $config['modelClass'] = get_called_class();
120

121 122
        return new ActiveQuery($config);
    }
123

124 125 126 127 128 129 130 131 132 133 134 135 136 137 138
    /**
     * 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.
     * @return string|array the collection name
     */
    public static function collectionName()
    {
        return Inflector::camel2id(StringHelper::basename(get_called_class()), '_');
    }
139

140 141 142 143 144 145 146 147
    /**
     * Return the Mongo collection instance for this AR class.
     * @return Collection collection instance.
     */
    public static function getCollection()
    {
        return static::getDb()->getCollection(static::collectionName());
    }
148

149 150 151 152 153 154 155 156 157 158 159 160
    /**
     * Returns the primary key name(s) for this AR class.
     * The default implementation will return ['_id'].
     *
     * Note that an array should be returned even for a collection with single primary key.
     *
     * @return string[] the primary keys of the associated Mongo collection.
     */
    public static function primaryKey()
    {
        return ['_id'];
    }
161

162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
    /**
     * Returns the list of all attribute names of the model.
     * 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'];
     * }
     * ~~~
     * @return array list of attribute names.
     */
    public function attributes()
    {
        throw new InvalidConfigException('The attributes() method of mongodb ActiveRecord has to be implemented by child classes.');
    }
179

180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223
    /**
     * Inserts a row into the associated Mongo collection 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 collection. 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 [[dirtyAttributes|changed attribute values]] will be inserted into database.
     *
     * If the primary key  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 collection.
     * @param  array      $attributes    list of attributes that need to be saved. Defaults to null,
     *                                   meaning all attributes that are loaded will be saved.
     * @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);
224

225 226
        return $result;
    }
227

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

250 251
        return true;
    }
252

253 254 255 256 257 258 259 260 261 262 263 264
    /**
     * @see ActiveRecord::update()
     * @throws StaleObjectException
     */
    protected function updateInternal($attributes = null)
    {
        if (!$this->beforeSave(false)) {
            return false;
        }
        $values = $this->getDirtyAttributes($attributes);
        if (empty($values)) {
            $this->afterSave(false);
265

266 267 268 269 270 271 272 273 274 275 276 277 278
            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.
        $rows = static::getCollection()->update($condition, $values);
279

280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358
        if ($lock !== null && !$rows) {
            throw new StaleObjectException('The object being updated is outdated.');
        }

        foreach ($values as $name => $value) {
            $this->setOldAttribute($name, $this->getAttribute($name));
        }
        $this->afterSave(false);

        return $rows;
    }

    /**
     * Deletes the document corresponding to this active record from the collection.
     *
     * 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 document from the collection;
     * 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.
     *
     * @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.
     * @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()) {
            $result = $this->deleteInternal();
            $this->afterDelete();
        }

        return $result;
    }

    /**
     * @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;
    }

    /**
     * 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
     * @return boolean      whether the two active records refer to the same row in the same Mongo collection.
     */
    public function equals($record)
    {
        if ($this->isNewRecord || $record->isNewRecord) {
            return false;
        }

        return $this->collectionName() === $record->collectionName() && (string) $this->getPrimaryKey() === (string) $record->getPrimaryKey();
    }
AlexGx committed
359
}