Doc comments at Mongo updated.

extensions/mongo/ActiveQuery.php

@@ -11,7 +11,23 @@ use yii\db\ActiveQueryInterface;
 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>
  * @since 2.0
@@ -22,8 +38,8 @@ class ActiveQuery extends Query implements ActiveQueryInterface
 
 	/**
 	 * Executes query and returns all results as an array.
-	 * @param Connection $db the DB connection used to create the DB command.
-	 * If null, the DB connection returned by [[modelClass]] will be used.
+	 * @param Connection $db the Mongo connection used to execute the query.
+	 * 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.
 	 */
 	public function all($db = null)
@@ -43,8 +59,8 @@ class ActiveQuery extends Query implements ActiveQueryInterface
 
 	/**
 	 * Executes query and returns a single row of result.
-	 * @param Connection $db the DB connection used to create the DB command.
-	 * If null, the DB connection returned by [[modelClass]] will be used.
+	 * @param Connection $db the Mongo connection used to execute the query.
+	 * 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]],
 	 * the query result may be either an array or an ActiveRecord object. Null will be returned
 	 * if the query results in nothing.

extensions/mongo/ActiveRecord.php

@@ -16,7 +16,7 @@ use yii\helpers\Inflector;
 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>
  * @since 2.0
@@ -24,8 +24,8 @@ use yii\helpers\StringHelper;
 abstract class ActiveRecord extends BaseActiveRecord
 {
 	/**
-	 * Returns the database connection used by this AR class.
-	 * By default, the "db" application component is used as the database connection.
+	 * Returns the Mongo connection used by this AR class.
+	 * 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.
 	 * @return Connection the database connection used by this AR class.
 	 */
@@ -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:
 	 *
 	 * ~~~
 	 * Customer::updateAll(['status' => 1], ['status' = 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.
+	 * @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 rows updated.
+	 * @return integer the number of documents updated.
 	 */
 	public static function updateAll($attributes, $condition = [], $options = [])
 	{
@@ -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,
 	 *
 	 * ~~~
@@ -63,10 +63,10 @@ abstract class ActiveRecord extends BaseActiveRecord
 	 *
 	 * @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.
+	 * @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 rows updated.
+	 * @return integer the number of documents updated.
 	 */
 	public static function updateAllCounters($counters, $condition = [], $options = [])
 	{
@@ -74,8 +74,8 @@ abstract class ActiveRecord extends BaseActiveRecord
 	}
 
 	/**
-	 * 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.
+	 * 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:
 	 *
@@ -83,10 +83,10 @@ abstract class ActiveRecord extends BaseActiveRecord
 	 * 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.
 	 * @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 = [])
 	{
@@ -99,7 +99,7 @@ abstract class ActiveRecord extends BaseActiveRecord
 
 	/**
 	 * 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
 	 * written for querying `Customer` purpose.)
 	 * @return ActiveQuery the newly created [[ActiveQuery]] instance.
@@ -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()]].
 	 * 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 the table name
+	 * @return string|array the collection name
 	 */
 	public static function collectionName()
 	{
@@ -138,9 +138,9 @@ abstract class ActiveRecord extends BaseActiveRecord
 	 * 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 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()
 	{
@@ -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:
 	 *
@@ -187,7 +187,7 @@ abstract class ActiveRecord extends BaseActiveRecord
 	 * 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;
+	 * 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]],
@@ -196,8 +196,8 @@ abstract class ActiveRecord extends BaseActiveRecord
 	 *
 	 * 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,
-	 * it will be populated with the actual value after insertion.
+	 * 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:
 	 *
@@ -209,9 +209,9 @@ abstract class ActiveRecord extends BaseActiveRecord
 	 * ~~~
 	 *
 	 * @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,
-	 * 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.
 	 * @throws \Exception in case insert failed.
 	 */
@@ -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:
 	 *
 	 * 1. call [[beforeDelete()]]. If the method returns false, it will skip the
 	 *    rest of the steps;
-	 * 2. delete the record from the database;
+	 * 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 rows 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.
+	 * @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.
@@ -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.
 	 * 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 database table.
+	 * @return boolean whether the two active records refer to the same row in the same Mongo collection.
 	 */
 	public function equals($record)
 	{

extensions/mongo/Collection.php

@@ -24,26 +24,38 @@ use Yii;
  * $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.
  * However Collection class provides the ability of "translating" common condition format used "yii\db\*"
  * into Mongo condition.
  * For example:
  * ~~~
  * $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));
  * // outputs :
  * [
  *     '$or' => [
- *         'name' => 'John',
+ *         [
+ *             'first_name' => 'John',
+ *             'last_name' => 'John',
+ *         ],
+ *         [
  *             '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 $fullName full name of this collection, including database name. This property is read-only.

extensions/mongo/Query.php

@@ -14,7 +14,22 @@ use yii\helpers\Json;
 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>
  * @since 2.0
@@ -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.
 	 * @return \MongoCursor mongo cursor instance.
 	 */
@@ -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 boolean $all whether to fetch all rows or only first one.
-	 * @param string|callable $indexBy
-	 * @throws Exception
-	 * @return array|boolean
+	 * @param string|callable $indexBy the column name or PHP callback,
+	 * by which the query results should be indexed by.
+	 * @throws Exception on failure.
+	 * @return array|boolean result.
 	 */
 	protected function fetchRows(\MongoCursor $cursor, $all = true, $indexBy = null)
 	{
@@ -173,7 +191,7 @@ class Query extends Component implements QueryInterface
 
 	/**
 	 * 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.
 	 * If this parameter is not given, the `mongo` application component will be used.
 	 * @return integer number of records
@@ -208,7 +226,7 @@ class Query extends Component implements QueryInterface
 
 	/**
 	 * 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.
 	 * @param Connection $db the Mongo connection used to execute the query.
 	 * If this parameter is not given, the `mongo` application component will be used.
@@ -221,7 +239,7 @@ class Query extends Component implements QueryInterface
 
 	/**
 	 * 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.
 	 * @param Connection $db the Mongo connection used to execute the query.
 	 * If this parameter is not given, the `mongo` application component will be used.
@@ -234,7 +252,7 @@ class Query extends Component implements QueryInterface
 
 	/**
 	 * 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.
 	 * @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.
@@ -247,7 +265,7 @@ class Query extends Component implements QueryInterface
 
 	/**
 	 * 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.
 	 * @param Connection $db the Mongo connection used to execute the query.
 	 * If this parameter is not given, the `mongo` application component will be used.