Skip to content

Y
yii2
Commit aa3a6dbe by Klimov Paul
Options

Doc comments at Mongo updated.

parent a4224df5
Showing with 94 additions and 48 deletions
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',
* '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.
......
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.
......
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