From a4224df518db8ea7702eb6177839e64b401e14d1 Mon Sep 17 00:00:00 2001 From: Paul Klimov Date: Tue, 3 Dec 2013 17:28:10 +0200 Subject: [PATCH] Doc comments at Mongo updated. --- extensions/mongo/Collection.php | 52 +++++++++++++++++++++++++++++++++++- extensions/mongo/Connection.php | 58 ++++++++++++++++++++++++++++++++++++++--- extensions/mongo/Database.php | 8 ------ 3 files changed, 105 insertions(+), 13 deletions(-) diff --git a/extensions/mongo/Collection.php b/extensions/mongo/Collection.php index aeae8a9..93307b6 100644 --- a/extensions/mongo/Collection.php +++ b/extensions/mongo/Collection.php @@ -14,6 +14,40 @@ use Yii; /** * Collection represents the Mongo collection information. * + * A collection object is usually created by calling [[Database::getCollection()]] or [[Connection::getCollection()]]. + * + * Collection provides the basic interface for the Mongo queries, mostly: insert, update, delete operations. + * For example: + * + * ~~~ + * $collection = Yii::$app->mongo->getCollection('customer'); + * $collection->insert(['name' => 'John Smith', 'status' => 1]); + * ~~~ + * + * 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]], + * ]; + * print_r($collection->buildCondition($condition)); + * // outputs : + * [ + * '$or' => [ + * 'name' => 'John', + * 'status' => ['$in' => [1, 2, 3]], + * ] + * ] + * ~~~ + * + * To perform "find" queries, please use [[Query]] instead. + * + * @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. + * * @author Paul Klimov * @since 2.0 */ @@ -62,7 +96,7 @@ class Collection extends Object } /** - * Creates an index on the collection and the specified fields + * Creates an index on the collection and the specified fields. * @param array|string $columns column name or list of column names. * If array is given, each element in the array has as key the field name, and as * value either 1 for ascending sort, or -1 for descending sort. @@ -233,6 +267,8 @@ class Collection extends Object /** * Updates the rows, which matches given criteria by given data. + * Note: for "multiple" mode Mongo requires explicit strategy "$set" or "$inc" + * to be specified for the "newData". If no strategy is passed "$set" will be used. * @param array $condition description of the objects to update. * @param array $newData the object with which to update the matching records. * @param array $options list of options in format: optionName => optionValue. @@ -418,6 +454,20 @@ class Collection extends Object * Performs aggregation using Mongo "map reduce" mechanism. * Note: this function will not return the aggregation result, instead it will * write it inside the another Mongo collection specified by "out" parameter. + * For example: + * + * ~~~ + * $customerCollection = Yii::$app->mongo->getCollection('customer'); + * $resultCollectionName = $customerCollection->mapReduce( + * 'function () {emit(this.status, this.amount)}', + * 'function (key, values) {return Array.sum(values)}', + * 'mapReduceOut', + * ['status' => 3] + * ); + * $query = new Query(); + * $results = $query->from($resultCollectionName)->all(); + * ~~~ + * * @param \MongoCode|string $map function, which emits map data from collection. * Argument will be automatically cast to [[\MongoCode]]. * @param \MongoCode|string $reduce function that takes two arguments (the map key diff --git a/extensions/mongo/Connection.php b/extensions/mongo/Connection.php index 725c757..5396e27 100644 --- a/extensions/mongo/Connection.php +++ b/extensions/mongo/Connection.php @@ -12,10 +12,58 @@ use yii\base\InvalidConfigException; use Yii; /** - * Class Connection + * Connection represents a connection to a MongoDb server. + * + * Connection works together with [[Database]] and [[Collection]] to provide data access + * to the Mongo database. They are wrappers of the [[MongoDB PHP extension]](http://us1.php.net/manual/en/book.mongo.php). + * + * To establish a DB connection, set [[dsn]] and then call [[open()]] to be true. + * + * The following example shows how to create a Connection instance and establish + * the DB connection: + * + * ~~~ + * $connection = new \yii\mongo\Connection([ + * 'dsn' => $dsn, + * ]); + * $connection->open(); + * ~~~ + * + * After the Mongo connection is established, one can access Mongo databases and collections: + * + * ~~~ + * $database = $connection->getDatabase('my_mongo_db'); + * $collection = $database->getCollection('customer'); + * $collection->insert(['name' => 'John Smith', 'status' => 1]); + * ~~~ + * + * You can work with several different databases at the same server using this class. + * However, while it is unlikely your application will actually need it, the Connection class + * provides ability to use [[defaultDatabaseName]] as well as a shortcut method [[getCollection()]] + * to retrieve a particular collection instance: + * + * ~~~ + * // get collection 'customer' from default database: + * $collection = $connection->getCollection('customer'); + * // get collection 'customer' from database 'mydatabase': + * $collection = $connection->getCollection(['mydatabase', 'customer']); + * ~~~ + * + * Connection is often used as an application component and configured in the application + * configuration like the following: + * + * ~~~ + * [ + * 'components' => [ + * 'mongo' => [ + * 'class' => '\yii\mongo\Connection', + * 'dsn' => 'mongodb://developer:password@localhost:27017/mydatabase', + * ], + * ], + * ] + * ~~~ * * @property boolean $isActive Whether the Mongo connection is established. This property is read-only. - * @property QueryBuilder $queryBuilder The query builder for the current Mongo connection. This property * is read-only. * * @author Paul Klimov @@ -30,8 +78,8 @@ class Connection extends Component * mongodb://[username:password@]host1[:port1][,host2[:port2:],...][/dbname] * For example: * mongodb://localhost:27017 - * mongodb://developer:somepassword@localhost:27017 - * mongodb://developer:somepassword@localhost:27017/mydatabase + * mongodb://developer:password@localhost:27017 + * mongodb://developer:password@localhost:27017/mydatabase */ public $dsn; /** @@ -48,6 +96,8 @@ class Connection extends Component public $options = []; /** * @var string name of the Mongo database to use by default. + * If this field left blank, connection instance will attempt to determine it from + * [[options]] and [[dsn]] automatically, if needed. */ public $defaultDatabaseName; /** diff --git a/extensions/mongo/Database.php b/extensions/mongo/Database.php index 2ff5abb..6495eb8 100644 --- a/extensions/mongo/Database.php +++ b/extensions/mongo/Database.php @@ -55,14 +55,6 @@ class Database extends Object } /** - * Drops this database. - */ - public function drop() - { - $this->mongoDb->drop(); - } - - /** * Creates new collection. * Note: Mongo creates new collections automatically on the first demand, * this method makes sense only for the migration script or for the case