From aa3a6dbe74132534beb730274bdac9c4c344795d Mon Sep 17 00:00:00 2001
From: Klimov Paul <klimov.paul@gmail.com>
Date: Tue, 3 Dec 2013 20:28:10 +0200
Subject: [PATCH] Doc comments at Mongo updated.
---
extensions/mongo/ActiveQuery.php | 26 +++++++++++++++++++++-----
extensions/mongo/ActiveRecord.php | 58 +++++++++++++++++++++++++++++-----------------------------
extensions/mongo/Collection.php | 22 +++++++++++++++++-----
extensions/mongo/Query.php | 36 +++++++++++++++++++++++++++---------
4 files changed, 94 insertions(+), 48 deletions(-)
diff --git a/extensions/mongo/ActiveQuery.php b/extensions/mongo/ActiveQuery.php
index 9031723..fc02df9 100644
--- a/extensions/mongo/ActiveQuery.php
+++ b/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.
diff --git a/extensions/mongo/ActiveRecord.php b/extensions/mongo/ActiveRecord.php
index 9c83080..41c1d7a 100644
--- a/extensions/mongo/ActiveRecord.php
+++ b/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)
{
diff --git a/extensions/mongo/Collection.php b/extensions/mongo/Collection.php
index 93307b6..5eca45a 100644
--- a/extensions/mongo/Collection.php
+++ b/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',
- * 'status' => ['$in' => [1, 2, 3]],
+ * [
+ * '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.
diff --git a/extensions/mongo/Query.php b/extensions/mongo/Query.php
index 1a00b08..8c46479 100644
--- a/extensions/mongo/Query.php
+++ b/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.
--
libgit2 0.27.1