Abstract Class yii\mongodb\ActiveRecord

Inheritanceyii\mongodb\ActiveRecord » yii\db\BaseActiveRecord
Subclassesyii\mongodb\file\ActiveRecord
Available since extension's version2.0
Source Code https://github.com/yiisoft/yii2-mongodb/blob/master/ActiveRecord.php

ActiveRecord is the base class for classes representing Mongo documents in terms of objects.

Public Methods

Hide inherited methods

Method Description Defined By
attributes() Returns the list of all attribute names of the model. yii\mongodb\ActiveRecord
collectionName() Declares the name of the Mongo collection associated with this AR class. yii\mongodb\ActiveRecord
delete() Deletes the document corresponding to this active record from the collection. yii\mongodb\ActiveRecord
deleteAll() Deletes documents in the collection using the provided conditions. yii\mongodb\ActiveRecord
equals() Returns a value indicating whether the given active record is the same as the current one. yii\mongodb\ActiveRecord
find() yii\mongodb\ActiveRecord
getCollection() Return the Mongo collection instance for this AR class. yii\mongodb\ActiveRecord
getDb() Returns the Mongo connection used by this AR class. yii\mongodb\ActiveRecord
insert() Inserts a row into the associated Mongo collection using the attribute values of this record. yii\mongodb\ActiveRecord
primaryKey() Returns the primary key name(s) for this AR class. yii\mongodb\ActiveRecord
updateAll() Updates all documents in the collection using the provided attribute values and conditions. yii\mongodb\ActiveRecord
updateAllCounters() Updates all documents in the collection using the provided counter changes and conditions. yii\mongodb\ActiveRecord

Method Details

Hide inherited methods

attributes() public method

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'];
}
public array attributes ( )
return array

List of attribute names.

throws \yii\base\InvalidConfigException

if not implemented

                public function attributes()
{
    throw new InvalidConfigException('The attributes() method of mongodb ActiveRecord has to be implemented by child classes.');
}

            
collectionName() public static method

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 collection is not named after this convention.

public static string|array collectionName ( )
return string|array

The collection name

                public static function collectionName()
{
    return Inflector::camel2id(StringHelper::basename(get_called_class()), '_');
}

            
delete() public method

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.

public integer|boolean delete ( )
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 \yii\db\StaleObjectException

if optimisticLock 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;
}

            
deleteAll() public static method

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]);
public static integer deleteAll ( $condition = [], $options = [] )
$condition array

Description of the objects to delete. Please refer to Query::where() on how to specify this parameter.

$options array

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);
}

            
deleteInternal() protected method
protected void deleteInternal ( )
throws \yii\db\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;
}

            
equals() public method

Returns a value indicating whether the given active record is the same as the current one.

The comparison is made by comparing the collection names and the primary key values of the two active records. If one of the records isNewRecord they are also considered not equal.

public boolean equals ( $record )
$record yii\mongodb\ActiveRecord

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();
}

            
find() public static method

public static yii\mongodb\ActiveQuery find ( )
return yii\mongodb\ActiveQuery

The newly created yii\mongodb\ActiveQuery instance.

                public static function find()
{
    return Yii::createObject(ActiveQuery::className(), [get_called_class()]);
}

            
getCollection() public static method

Return the Mongo collection instance for this AR class.

public static yii\mongodb\Collection getCollection ( )
return yii\mongodb\Collection

Collection instance.

                public static function getCollection()
{
    return static::getDb()->getCollection(static::collectionName());
}

            
getDb() public static method

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.

public static yii\mongodb\Connection getDb ( )
return yii\mongodb\Connection

The database connection used by this AR class.

                public static function getDb()
{
    return \Yii::$app->get('mongodb');
}

            
insert() public method

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 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();
public boolean insert ( $runValidation true, $attributes null )
$runValidation boolean

Whether to perform validation before saving the record. If the validation fails, the record will not be inserted into the collection.

$attributes array

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);
    return $result;
}

            
insertInternal() protected method
protected void insertInternal ( $attributes null )
$attributes

                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) {
            if (isset($currentAttributes[$key])) {
                $values[$key] = $currentAttributes[$key];
            }
        }
    }
    $newId = static::getCollection()->insert($values);
    $this->setAttribute('_id', $newId);
    $values['_id'] = $newId;
    $changedAttributes = array_fill_keys(array_keys($values), null);
    $this->setOldAttributes($values);
    $this->afterSave(true, $changedAttributes);
    return true;
}

            
primaryKey() public static method

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.

public static string[] primaryKey ( )
return string[]

The primary keys of the associated Mongo collection.

                public static function primaryKey()
{
    return ['_id'];
}

            
updateAll() public static method

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]);
public static integer updateAll ( $attributes, $condition = [], $options = [] )
$attributes array

Attribute values (name-value pairs) to be saved into the collection

$condition array

Description of the objects to update. Please refer to Query::where() on how to specify this parameter.

$options array

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);
}

            
updateAllCounters() public static method

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]);
public static integer updateAllCounters ( $counters, $condition = [], $options = [] )
$counters array

The counters to be updated (attribute name => increment value). Use negative values if you want to decrement the counters.

$condition array

Description of the objects to update. Please refer to Query::where() on how to specify this parameter.

$options array

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);
}

            
updateInternal() protected method

See also \yii\mongodb\ActiveRecord::update().

protected void updateInternal ( $attributes null )
$attributes
throws \yii\db\StaleObjectException

                protected function updateInternal($attributes = null)
{
    if (!$this->beforeSave(false)) {
        return false;
    }
    $values = $this->getDirtyAttributes($attributes);
    if (empty($values)) {
        $this->afterSave(false, $values);
        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);
    if ($lock !== null && !$rows) {
        throw new StaleObjectException('The object being updated is outdated.');
    }
    if (isset($values[$lock])) {
        $this->$lock = $values[$lock];
    }
    $changedAttributes = [];
    foreach ($values as $name => $value) {
        $changedAttributes[$name] = $this->getOldAttribute($name);
        $this->setOldAttribute($name, $value);
    }
    $this->afterSave(false, $changedAttributes);
    return $rows;
}