From aa3a6dbe74132534beb730274bdac9c4c344795d Mon Sep 17 00:00:00 2001 From: Klimov Paul 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 * @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 * @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 * @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.