Commit a4224df5 by Paul Klimov

Doc comments at Mongo updated.

parent 3e744b73
......@@ -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 <klimov.paul@gmail.com>
* @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
......
......@@ -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 <klimov.paul@gmail.com>
......@@ -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;
/**
......
......@@ -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
......
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