Commit aa3a6dbe by Klimov Paul

Doc comments at Mongo updated.

parent a4224df5
...@@ -11,7 +11,23 @@ use yii\db\ActiveQueryInterface; ...@@ -11,7 +11,23 @@ use yii\db\ActiveQueryInterface;
use yii\db\ActiveQueryTrait; use yii\db\ActiveQueryTrait;
/** /**
* Class ActiveQuery * ActiveQuery represents a Mongo query associated with an Active Record class.
*
* ActiveQuery instances are usually created by [[ActiveRecord::find()]].
*
* 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.
* - [[asArray()]]: whether to return each record as an array.
*
* These options can be configured using methods of the same name. For example:
*
* ~~~
* $customers = Customer::find()->with('orders')->asArray()->all();
* ~~~
* *
* @author Paul Klimov <klimov.paul@gmail.com> * @author Paul Klimov <klimov.paul@gmail.com>
* @since 2.0 * @since 2.0
...@@ -22,8 +38,8 @@ class ActiveQuery extends Query implements ActiveQueryInterface ...@@ -22,8 +38,8 @@ class ActiveQuery extends Query implements ActiveQueryInterface
/** /**
* Executes query and returns all results as an array. * Executes query and returns all results as an array.
* @param Connection $db the DB connection used to create the DB command. * @param Connection $db the Mongo connection used to execute the query.
* If null, the DB connection returned by [[modelClass]] will be used. * If null, the Mongo connection returned by [[modelClass]] will be used.
* @return array the query results. If the query results in nothing, an empty array will be returned. * @return array the query results. If the query results in nothing, an empty array will be returned.
*/ */
public function all($db = null) public function all($db = null)
...@@ -43,8 +59,8 @@ class ActiveQuery extends Query implements ActiveQueryInterface ...@@ -43,8 +59,8 @@ class ActiveQuery extends Query implements ActiveQueryInterface
/** /**
* Executes query and returns a single row of result. * Executes query and returns a single row of result.
* @param Connection $db the DB connection used to create the DB command. * @param Connection $db the Mongo connection used to execute the query.
* If null, the DB connection returned by [[modelClass]] will be used. * If null, the Mongo connection returned by [[modelClass]] will be used.
* @return ActiveRecord|array|null a single row of query result. Depending on the setting of [[asArray]], * @return ActiveRecord|array|null a single row of query result. Depending on the setting of [[asArray]],
* the query result may be either an array or an ActiveRecord object. Null will be returned * the query result may be either an array or an ActiveRecord object. Null will be returned
* if the query results in nothing. * if the query results in nothing.
......
...@@ -16,7 +16,7 @@ use yii\helpers\Inflector; ...@@ -16,7 +16,7 @@ use yii\helpers\Inflector;
use yii\helpers\StringHelper; use yii\helpers\StringHelper;
/** /**
* Class ActiveRecord * ActiveRecord is the base class for classes representing Mongo documents in terms of objects.
* *
* @author Paul Klimov <klimov.paul@gmail.com> * @author Paul Klimov <klimov.paul@gmail.com>
* @since 2.0 * @since 2.0
...@@ -24,8 +24,8 @@ use yii\helpers\StringHelper; ...@@ -24,8 +24,8 @@ use yii\helpers\StringHelper;
abstract class ActiveRecord extends BaseActiveRecord abstract class ActiveRecord extends BaseActiveRecord
{ {
/** /**
* Returns the database connection used by this AR class. * Returns the Mongo connection used by this AR class.
* By default, the "db" application component is used as the database connection. * By default, the "mongo" application component is used as the Mongo connection.
* You may override this method if you want to use a different 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. * @return Connection the database connection used by this AR class.
*/ */
...@@ -35,18 +35,18 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -35,18 +35,18 @@ abstract class ActiveRecord extends BaseActiveRecord
} }
/** /**
* Updates the whole table using the provided attribute values and conditions. * 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: * For example, to change the status to be 1 for all customers whose status is 2:
* *
* ~~~ * ~~~
* Customer::updateAll(['status' => 1], ['status' = 2]); * Customer::updateAll(['status' => 1], ['status' = 2]);
* ~~~ * ~~~
* *
* @param array $attributes attribute values (name-value pairs) to be saved into the table * @param array $attributes attribute values (name-value pairs) to be saved into the collection
* @param array $condition the conditions that will be put in the WHERE part of the UPDATE SQL. * @param array $condition description of the objects to update.
* Please refer to [[Query::where()]] on how to specify this parameter. * Please refer to [[Query::where()]] on how to specify this parameter.
* @param array $options list of options in format: optionName => optionValue. * @param array $options list of options in format: optionName => optionValue.
* @return integer the number of rows updated. * @return integer the number of documents updated.
*/ */
public static function updateAll($attributes, $condition = [], $options = []) public static function updateAll($attributes, $condition = [], $options = [])
{ {
...@@ -54,7 +54,7 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -54,7 +54,7 @@ abstract class ActiveRecord extends BaseActiveRecord
} }
/** /**
* Updates the whole table using the provided counter changes and conditions. * Updates all documents in the collection using the provided counter changes and conditions.
* For example, to increment all customers' age by 1, * For example, to increment all customers' age by 1,
* *
* ~~~ * ~~~
...@@ -63,10 +63,10 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -63,10 +63,10 @@ abstract class ActiveRecord extends BaseActiveRecord
* *
* @param array $counters the counters to be updated (attribute name => increment value). * @param array $counters the counters to be updated (attribute name => increment value).
* Use negative values if you want to decrement the counters. * 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. * @param array $condition description of the objects to update.
* Please refer to [[Query::where()]] on how to specify this parameter. * Please refer to [[Query::where()]] on how to specify this parameter.
* @param array $options list of options in format: optionName => optionValue. * @param array $options list of options in format: optionName => optionValue.
* @return integer the number of rows updated. * @return integer the number of documents updated.
*/ */
public static function updateAllCounters($counters, $condition = [], $options = []) public static function updateAllCounters($counters, $condition = [], $options = [])
{ {
...@@ -74,8 +74,8 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -74,8 +74,8 @@ abstract class ActiveRecord extends BaseActiveRecord
} }
/** /**
* Deletes rows in the table using the provided conditions. * Deletes documents in the collection using the provided conditions.
* WARNING: If you do not specify any condition, this method will delete ALL rows in the table. * 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: * For example, to delete all customers whose status is 3:
* *
...@@ -83,10 +83,10 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -83,10 +83,10 @@ abstract class ActiveRecord extends BaseActiveRecord
* Customer::deleteAll('status = 3'); * Customer::deleteAll('status = 3');
* ~~~ * ~~~
* *
* @param array $condition the conditions that will be put in the WHERE part of the DELETE SQL. * @param array $condition description of the objects to delete.
* Please refer to [[Query::where()]] on how to specify this parameter. * Please refer to [[Query::where()]] on how to specify this parameter.
* @param array $options list of options in format: optionName => optionValue. * @param array $options list of options in format: optionName => optionValue.
* @return integer the number of rows updated. * @return integer the number of documents deleted.
*/ */
public static function deleteAll($condition = [], $options = []) public static function deleteAll($condition = [], $options = [])
{ {
...@@ -99,7 +99,7 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -99,7 +99,7 @@ abstract class ActiveRecord extends BaseActiveRecord
/** /**
* Creates an [[ActiveQuery]] instance. * Creates an [[ActiveQuery]] instance.
* This method is called by [[find()]] to start a SELECT query. * This method is called by [[find()]] to start a "find" command.
* You may override this method to return a customized query (e.g. `CustomerQuery` specified * You may override this method to return a customized query (e.g. `CustomerQuery` specified
* written for querying `Customer` purpose.) * written for querying `Customer` purpose.)
* @return ActiveQuery the newly created [[ActiveQuery]] instance. * @return ActiveQuery the newly created [[ActiveQuery]] instance.
...@@ -118,7 +118,7 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -118,7 +118,7 @@ abstract class ActiveRecord extends BaseActiveRecord
* By default this method returns the class name as the collection name by calling [[Inflector::camel2id()]]. * By default this method returns the class name as the collection name by calling [[Inflector::camel2id()]].
* For example, 'Customer' becomes 'customer', and 'OrderItem' becomes * For example, 'Customer' becomes 'customer', and 'OrderItem' becomes
* 'order_item'. You may override this method if the table is not named after this convention. * 'order_item'. You may override this method if the table is not named after this convention.
* @return string the table name * @return string|array the collection name
*/ */
public static function collectionName() public static function collectionName()
{ {
...@@ -138,9 +138,9 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -138,9 +138,9 @@ abstract class ActiveRecord extends BaseActiveRecord
* Returns the primary key name(s) for this AR class. * Returns the primary key name(s) for this AR class.
* The default implementation will return ['_id']. * The default implementation will return ['_id'].
* *
* Note that an array should be returned even for a table with single primary key. * Note that an array should be returned even for a collection with single primary key.
* *
* @return string[] the primary keys of the associated database table. * @return string[] the primary keys of the associated Mongo collection.
*/ */
public static function primaryKey() public static function primaryKey()
{ {
...@@ -178,7 +178,7 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -178,7 +178,7 @@ abstract class ActiveRecord extends BaseActiveRecord
} }
/** /**
* Inserts a row into the associated database table using the attribute values of this record. * Inserts a row into the associated Mongo collection using the attribute values of this record.
* *
* This method performs the following steps in order: * This method performs the following steps in order:
* *
...@@ -187,7 +187,7 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -187,7 +187,7 @@ abstract class ActiveRecord extends BaseActiveRecord
* 2. call [[afterValidate()]] when `$runValidation` is true. * 2. call [[afterValidate()]] when `$runValidation` is true.
* 3. call [[beforeSave()]]. If the method returns false, it will skip the * 3. call [[beforeSave()]]. If the method returns false, it will skip the
* rest of the steps; * rest of the steps;
* 4. insert the record into database. If this fails, 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()]]; * 5. call [[afterSave()]];
* *
* In the above step 1, 2, 3 and 5, events [[EVENT_BEFORE_VALIDATE]], * In the above step 1, 2, 3 and 5, events [[EVENT_BEFORE_VALIDATE]],
...@@ -196,8 +196,8 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -196,8 +196,8 @@ abstract class ActiveRecord extends BaseActiveRecord
* *
* Only the [[dirtyAttributes|changed attribute values]] will be inserted into database. * Only the [[dirtyAttributes|changed attribute values]] will be inserted into database.
* *
* If the table's primary key is auto-incremental and is null during insertion, * If the primary key is null during insertion, it will be populated with the actual
* it will be populated with the actual value after insertion. * value after insertion.
* *
* For example, to insert a customer record: * For example, to insert a customer record:
* *
...@@ -209,9 +209,9 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -209,9 +209,9 @@ abstract class ActiveRecord extends BaseActiveRecord
* ~~~ * ~~~
* *
* @param boolean $runValidation whether to perform validation before saving the record. * @param boolean $runValidation whether to perform validation before saving the record.
* If the validation fails, the record will not be inserted into the database. * 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, * @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. * meaning all attributes that are loaded will be saved.
* @return boolean whether the attributes are valid and the record is inserted successfully. * @return boolean whether the attributes are valid and the record is inserted successfully.
* @throws \Exception in case insert failed. * @throws \Exception in case insert failed.
*/ */
...@@ -287,20 +287,20 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -287,20 +287,20 @@ abstract class ActiveRecord extends BaseActiveRecord
} }
/** /**
* Deletes the table row corresponding to this active record. * Deletes the document corresponding to this active record from the collection.
* *
* This method performs the following steps in order: * This method performs the following steps in order:
* *
* 1. call [[beforeDelete()]]. If the method returns false, it will skip the * 1. call [[beforeDelete()]]. If the method returns false, it will skip the
* rest of the steps; * rest of the steps;
* 2. delete the record from the database; * 2. delete the document from the collection;
* 3. call [[afterDelete()]]. * 3. call [[afterDelete()]].
* *
* In the above step 1 and 3, events named [[EVENT_BEFORE_DELETE]] and [[EVENT_AFTER_DELETE]] * In the above step 1 and 3, events named [[EVENT_BEFORE_DELETE]] and [[EVENT_AFTER_DELETE]]
* will be raised by the corresponding methods. * will be raised by the corresponding methods.
* *
* @return integer|boolean the number of rows deleted, or false if the deletion is unsuccessful for some reason. * @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 rows deleted is 0, even though the deletion execution is successful. * 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 * @throws StaleObjectException if [[optimisticLock|optimistic locking]] is enabled and the data
* being deleted is outdated. * being deleted is outdated.
* @throws \Exception in case delete failed. * @throws \Exception in case delete failed.
...@@ -331,7 +331,7 @@ abstract class ActiveRecord extends BaseActiveRecord ...@@ -331,7 +331,7 @@ abstract class ActiveRecord extends BaseActiveRecord
* The comparison is made by comparing the table names and the primary key values of the two active records. * 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. * If one of the records [[isNewRecord|is new]] they are also considered not equal.
* @param ActiveRecord $record record to compare to * @param ActiveRecord $record record to compare to
* @return boolean whether the two active records refer to the same row in the same database table. * @return boolean whether the two active records refer to the same row in the same Mongo collection.
*/ */
public function equals($record) public function equals($record)
{ {
......
...@@ -24,26 +24,38 @@ use Yii; ...@@ -24,26 +24,38 @@ use Yii;
* $collection->insert(['name' => 'John Smith', 'status' => 1]); * $collection->insert(['name' => 'John Smith', 'status' => 1]);
* ~~~ * ~~~
* *
* To perform "find" queries, please use [[Query]] instead.
*
* Mongo uses JSON format to specify query conditions with quite specific syntax. * Mongo uses JSON format to specify query conditions with quite specific syntax.
* However Collection class provides the ability of "translating" common condition format used "yii\db\*" * However Collection class provides the ability of "translating" common condition format used "yii\db\*"
* into Mongo condition. * into Mongo condition.
* For example: * For example:
* ~~~ * ~~~
* $condition = [ * $condition = [
* ['AND', 'name', 'John'], * [
* ['OR', 'status', [1, 2, 3]], * 'OR',
* ['AND', ['first_name' => 'John'], ['last_name' => 'Smith']],
* ['status' => [1, 2, 3]]
* ],
* ]; * ];
* print_r($collection->buildCondition($condition)); * print_r($collection->buildCondition($condition));
* // outputs : * // outputs :
* [ * [
* '$or' => [ * '$or' => [
* 'name' => 'John', * [
* 'first_name' => 'John',
* 'last_name' => 'John',
* ],
* [
* 'status' => ['$in' => [1, 2, 3]], * 'status' => ['$in' => [1, 2, 3]],
* ] * ]
* ] * ]
* ]
* ~~~ * ~~~
* *
* To perform "find" queries, please use [[Query]] instead. * Note: condition values for the key '_id' will be automatically cast to [[\MongoId]] instance,
* even if they are plain strings. However if you have other columns, containing [[\MongoId]], you
* should take care of possible typecast on your own.
* *
* @property string $name name of this collection. This property is read-only. * @property string $name name of this collection. This property is read-only.
* @property string $fullName full name of this collection, including database name. This property is read-only. * @property string $fullName full name of this collection, including database name. This property is read-only.
......
...@@ -14,7 +14,22 @@ use yii\helpers\Json; ...@@ -14,7 +14,22 @@ use yii\helpers\Json;
use Yii; use Yii;
/** /**
* Class Query * Query represents Mongo "find" operation.
*
* Query provides a set of methods to facilitate the specification of "find" command.
* These methods can be chained together.
*
* For example,
*
* ~~~
* $query = new Query;
* // compose the query
* $query->select(['name', 'status'])
* ->from('customer')
* ->limit(10);
* // execute the query
* $rows = $query->all();
* ~~~
* *
* @author Paul Klimov <klimov.paul@gmail.com> * @author Paul Klimov <klimov.paul@gmail.com>
* @since 2.0 * @since 2.0
...@@ -75,6 +90,7 @@ class Query extends Component implements QueryInterface ...@@ -75,6 +90,7 @@ class Query extends Component implements QueryInterface
} }
/** /**
* Builds the Mongo cursor for this query.
* @param Connection $db the database connection used to execute the query. * @param Connection $db the database connection used to execute the query.
* @return \MongoCursor mongo cursor instance. * @return \MongoCursor mongo cursor instance.
*/ */
...@@ -105,11 +121,13 @@ class Query extends Component implements QueryInterface ...@@ -105,11 +121,13 @@ class Query extends Component implements QueryInterface
} }
/** /**
* Fetches rows from the given Mongo cursor.
* @param \MongoCursor $cursor Mongo cursor instance to fetch data from. * @param \MongoCursor $cursor Mongo cursor instance to fetch data from.
* @param boolean $all whether to fetch all rows or only first one. * @param boolean $all whether to fetch all rows or only first one.
* @param string|callable $indexBy * @param string|callable $indexBy the column name or PHP callback,
* @throws Exception * by which the query results should be indexed by.
* @return array|boolean * @throws Exception on failure.
* @return array|boolean result.
*/ */
protected function fetchRows(\MongoCursor $cursor, $all = true, $indexBy = null) protected function fetchRows(\MongoCursor $cursor, $all = true, $indexBy = null)
{ {
...@@ -173,7 +191,7 @@ class Query extends Component implements QueryInterface ...@@ -173,7 +191,7 @@ class Query extends Component implements QueryInterface
/** /**
* Returns the number of records. * Returns the number of records.
* @param string $q the COUNT expression. Defaults to '*'. * @param string $q kept to match [[QueryInterface]], its value is ignored.
* @param Connection $db the Mongo connection used to execute the query. * @param Connection $db the Mongo connection used to execute the query.
* If this parameter is not given, the `mongo` application component will be used. * If this parameter is not given, the `mongo` application component will be used.
* @return integer number of records * @return integer number of records
...@@ -208,7 +226,7 @@ class Query extends Component implements QueryInterface ...@@ -208,7 +226,7 @@ class Query extends Component implements QueryInterface
/** /**
* Returns the sum of the specified column values. * Returns the sum of the specified column values.
* @param string $q the column name or expression. * @param string $q the column name.
* Make sure you properly quote column names in the expression. * Make sure you properly quote column names in the expression.
* @param Connection $db the Mongo connection used to execute the query. * @param Connection $db the Mongo connection used to execute the query.
* If this parameter is not given, the `mongo` application component will be used. * If this parameter is not given, the `mongo` application component will be used.
...@@ -221,7 +239,7 @@ class Query extends Component implements QueryInterface ...@@ -221,7 +239,7 @@ class Query extends Component implements QueryInterface
/** /**
* Returns the average of the specified column values. * Returns the average of the specified column values.
* @param string $q the column name or expression. * @param string $q the column name.
* Make sure you properly quote column names in the expression. * Make sure you properly quote column names in the expression.
* @param Connection $db the Mongo connection used to execute the query. * @param Connection $db the Mongo connection used to execute the query.
* If this parameter is not given, the `mongo` application component will be used. * If this parameter is not given, the `mongo` application component will be used.
...@@ -234,7 +252,7 @@ class Query extends Component implements QueryInterface ...@@ -234,7 +252,7 @@ class Query extends Component implements QueryInterface
/** /**
* Returns the minimum of the specified column values. * Returns the minimum of the specified column values.
* @param string $q the column name or expression. * @param string $q the column name.
* Make sure you properly quote column names in the expression. * Make sure you properly quote column names in the expression.
* @param Connection $db the database connection used to generate the SQL statement. * @param Connection $db the database connection used to generate the SQL statement.
* If this parameter is not given, the `db` application component will be used. * If this parameter is not given, the `db` application component will be used.
...@@ -247,7 +265,7 @@ class Query extends Component implements QueryInterface ...@@ -247,7 +265,7 @@ class Query extends Component implements QueryInterface
/** /**
* Returns the maximum of the specified column values. * Returns the maximum of the specified column values.
* @param string $q the column name or expression. * @param string $q the column name.
* Make sure you properly quote column names in the expression. * Make sure you properly quote column names in the expression.
* @param Connection $db the Mongo connection used to execute the query. * @param Connection $db the Mongo connection used to execute the query.
* If this parameter is not given, the `mongo` application component will be used. * If this parameter is not given, the `mongo` application component will be used.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment