Skip to content

M
mongo-php-library
Commit 6d4a1d31 authored by Jeremy Mikola's avatar Jeremy Mikola
Browse files
Options

Update MongoDB\Database documentation

parent cbb7f43a
Show whitespace changes
Inline Side-by-side
Showing with 548 additions and 506 deletions
docs/includes/apiargs-MongoDBDatabase-method-command-option.yaml
View file @ 6d4a1d31
......@@ -3,10 +3,18 @@ source:
ref: readPreference
operation: MongoDB\\Database::command
position: 1
description: |
The read preference to use when executing the command. This may be used when
issuing the command to a replica set or shard cluster to ensure that the
driver sets the wire protocol accordingly or adds the read preference to the
command document, respectively. Defaults to the Database's read preference.
---
source:
file: apiargs-common-option.yaml
ref: typeMap
operation: MongoDB\\Database::command
position: 2
description: |
Type map for BSON deserialization. This will be applied to the returned
cursor. Defaults to the database's type map.
...
docs/includes/apiargs-MongoDBDatabase-method-command-param.yaml
View file @ 6d4a1d31
arg_name: param
name: $command
type: string
type: array|object
description: |
The name of the :manual:`database command </reference/command>`
to execute.
The :manual:`database command </reference/command>` document.
interface: phpmethod
operation: MongoDB\\Database::command
optional: false
......
docs/includes/apiargs-MongoDBDatabase-method-construct-option.yaml
View file @ 6d4a1d31
......@@ -3,17 +3,39 @@ source:
ref: readConcern
operation: MongoDB\\Database::__construct
position: 1
replacement:
resource: "database"
parent: "manager"
---
source:
file: apiargs-common-option.yaml
ref: readPreference
operation: MongoDB\\Database::__construct
position: 2
replacement:
resource: "database"
parent: "manager"
---
source:
file: apiargs-common-option.yaml
ref: typeMap
arg_name: option
name: typeMap
type: array
description: |
Default :php:`type map
<manual/en/mongodb.persistence.deserialization.php#mongodb.persistence.typemaps>`
to apply to cursors. The type map determines how BSON documents are converted
to PHP values which determines. The |php-library| uses the following type map
by default:
.. code-block:: php
[
'array' => 'MongoDB\Model\BSONArray',
'document' => 'MongoDB\Model\BSONDocument',
'root' => 'MongoDB\Model\BSONDocument',
]
interface: phpmethod
operation: MongoDB\\Database::__construct
optional: true
position: 3
---
source:
......@@ -21,4 +43,7 @@ source:
ref: writeConcern
operation: MongoDB\\Database::__construct
position: 4
replacement:
resource: "database"
parent: "manager"
...
docs/includes/apiargs-MongoDBDatabase-method-construct-param.yaml
View file @ 6d4a1d31
......@@ -5,8 +5,8 @@ operation: MongoDB\\Database::__construct
position: 1
---
source:
ref: $databaseName
file: apiargs-common-param.yaml
ref: $databaseName
operation: MongoDB\\Database::__construct
position: 2
---
......@@ -14,5 +14,5 @@ source:
ref: $options
file: apiargs-common-param.yaml
operation: MongoDB\\Database::__construct
position: 2
position: 3
...
docs/includes/apiargs-MongoDBDatabase-method-createCollection-option.yaml
View file @ 6d4a1d31
......@@ -2,66 +2,77 @@ arg_name: option
name: autoIndexId
type: boolean
description: |
*Default: true*. Specify false to disable the automatic creation of
an index on the _id field.
Specify ``false`` to disable the automatic creation of an index on the ``_id``
field.
.. important::
For replica sets, do not set ``autoIndexId`` to ``false``.
.. deprecated:: 3.2. The ``autoIndexId`` option will be removed in MongoDB v3.4.
optional: true
.. deprecated:: 3.2. The ``autoIndexId`` option will be removed in MongoDB 3.4.
interface: phpmethod
operation: MongoDB\\Database::createCollection
position: 1
---
arg_name: option
name: indexOptionDefaults
type: array
description: |
Allows users to specify a default configuration for indexes when
creating a collection.
The ``indexOptionDefaults`` option accepts a ``storageEngine`` document,
which should take the following form::
{ <storage-engine-name>: <options> }
Storage engine configurations specified when creating indexes are
validated and logged to the :term:`oplog` during replication to support
replica sets with members that use different storage engines.
optional: true
interface: phpmethod
operation: MongoDB\\Database::createCollection
position: 2
position: 1
---
arg_name: option
name: capped
type: boolean
description: |
To create a capped collection, specify ``true``. If you specify
``true``, you must also set a maximum size in the ``size`` option.
optional: true
To create a capped collection, specify ``true``. If you specify ``true``, you
must also set a maximum size in the ``size`` option.
interface: phpmethod
operation: MongoDB\\Database::createCollection
optional: true
position: 3
---
arg_name: option
name: size
name: flags
type: integer
description: |
Specify a maximum size in bytes for a capped collection. Once a
capped collection reaches its maximum size, MongoDB removes the older
documents to make space for the new documents. The ``size`` option is
required for capped collections and ignored for other collections.
optional: true
Available for the MMAPv1 storage engine only to set the ``usePowerOf2Sizes``
and ``noPadding`` flags.
The |php-library| provides constants that you can combine with a :php:`bitwise
OR operator <language.operators.bitwise>` to set the flag values:
- ``MongoDB\Operation\CreateCollection::USE_POWER_OF_2_SIZES``: ``1``
- ``MongoDB\Operation\CreateCollection::NO_PADDING``: ``2``
Defaults to ``1``.
.. note::
MongoDB 3.0 and later ignores the ``usePowerOf2Sizes`` flag. See
:manual:`collMod </reference/command/collMod>` and
:manual:`db.createCollection()
</reference/method/db.createCollection>` for more information.
interface: phpmethod
operation: MongoDB\\Database::createCollection
optional: true
position: 4
---
arg_name: option
name: indexOptionDefaults
type: array|object
description: |
Allows users to specify a default configuration for indexes when creating a
collection.
The ``indexOptionDefaults`` option accepts a ``storageEngine`` document,
which should take the following form::
{ <storage-engine-name>: <options> }
Storage engine configurations specified when creating indexes are validated
and logged to the :term:`oplog` during replication to support replica sets
with members that use different storage engines.
interface: phpmethod
operation: MongoDB\\Database::createCollection
optional: true
position: 5
---
arg_name: option
name: max
type: integer
description: |
......@@ -75,11 +86,30 @@ description: |
interface: phpmethod
operation: MongoDB\\Database::createCollection
optional: true
position: 5
position: 6
---
source:
file: apiargs-common-option.yaml
ref: maxTimeMS
operation: MongoDB\\Database::createCollection
position: 7
---
arg_name: option
name: size
type: integer
description: |
Specify a maximum size in bytes for a capped collection. Once a capped
collection reaches its maximum size, MongoDB removes the older documents to
make space for the new documents. The ``size`` option is required for capped
collections and ignored for other collections.
interface: phpmethod
operation: MongoDB\\Database::createCollection
optional: true
position: 8
---
arg_name: option
name: storageEngine
type: array
type: array|object
description: |
Available for the WiredTiger storage engine only.
......@@ -95,144 +125,108 @@ description: |
interface: phpmethod
operation: MongoDB\\Database::createCollection
optional: true
position: 6
position: 9
---
arg_name: option
name: flags
type: integer
description: |
Available for the MMAPv1 storage engine only to set the
``usePowerOf2Sizes`` and ``noPadding`` flags.
The |php-library| provides constants that you can combine with a
:php:`bitwise OR operator <language.operators.bitwise>` to set the
flag values:
- ``MongoDB\Operation\CreateCollection::USE_POWER_OF_2_SIZES``: ``1``
- ``MongoDB\Operation\CreateCollection::NO_PADDING``: ``2``
Defaults to ``1``.
.. note::
MongoDB 3.0 and later ignores the ``usePowerOf2Sizes`` flag. See
:manual:`collMod </reference/command/collMod>` and
:manual:`db.createCollection()
</reference/method/db.createCollection>` for more information.
interface: phpmethod
source:
file: apiargs-common-option.yaml
ref: typeMap
operation: MongoDB\\Database::createCollection
optional: true
position: 7
position: 10
description: |
Type map for BSON deserialization. This will be used for the returned command
result document. Defaults to the database's type map.
---
arg_name: option
name: validator
type: array
description: |
Allows users to specify :manual:`validation rules or expressions
</core/document-validation>` for the collection. For more information,
see :manual:`Document Validation </core/document-validation>`
in the MongoDB manual.
</core/document-validation>` for the collection. For more information, see
:manual:`Document Validation </core/document-validation>` in the MongoDB
manual.
The ``validator`` option takes an array that specifies the
validation rules or expressions. You can specify the expressions using
the same operators as MongoDB's :manual:`query operators </reference/operator/query>`
with the exception of :query:`$geoNear`, :query:`$near`,
:query:`$nearSphere`, :query:`$text`, and :query:`$where`.
The ``validator`` option takes an array that specifies the validation rules or
expressions. You can specify the expressions using the same operators as
MongoDB's :manual:`query operators </reference/operator/query>` with the
exception of :query:`$geoNear`, :query:`$near`, :query:`$nearSphere`,
:query:`$text`, and :query:`$where`.
.. note::
- Validation occurs during updates and inserts. Existing
documents do not undergo validation checks until modification.
- Validation occurs during updates and inserts. Existing documents do not
undergo validation checks until modification.
- You cannot specify a validator for collections in the ``admin``,
``local``, and ``config`` databases.
- You cannot specify a validator for ``system.*`` collections.
operation: MongoDB\\Database::createCollection
interface: phpmethod
optional: true
position: 8
position: 11
---
arg_name: option
name: validationLevel
name: validationAction
type: string
description: |
Determines how strictly MongoDB applies the
validation rules to existing documents during an update.
Determines whether to ``error`` on invalid documents or just ``warn`` about
the violations but allow invalid documents to be inserted.
.. important::
Validation of documents only applies to those documents as determined by
the ``validationLevel``.
.. list-table::
:header-rows: 1
* - ``validationLevel``
* - ``validationAction``
- Description
* - ``"off"``
- No validation for inserts or updates.
* - ``"strict"``
- **Default** Apply validation rules to all inserts and all
updates.
* - ``"error"``
* - ``"moderate"``
- **Default**. Documents must pass validation before the write occurs.
Otherwise, the write operation fails.
- Apply validation rules to inserts and to updates on existing *valid*
documents. Do not apply rules to updates on existing *invalid*
documents.
* - ``"warn"``
- Documents do not have to pass validation. If the document fails
validation, the write operation logs the validation failure.
interface: phpmethod
operation: MongoDB\\Database::createCollection
optional: true
position: 9
position: 12
---
arg_name: option
name: validationAction
name: validationLevel
type: string
description: |
Determines whether to ``error`` on invalid documents or just ``warn``
about the violations but allow invalid documents to be inserted.
.. important::
Validation of documents only applies to those documents as
determined by the ``validationLevel``.
Determines how strictly MongoDB applies the validation rules to existing
documents during an update.
.. list-table::
:header-rows: 1
* - ``validationAction``
* - ``validationLevel``
- Description
* - ``"error"``
* - ``"off"``
- **Default** Documents must pass validation before the write occurs.
Otherwise, the write operation fails.
- No validation for inserts or updates.
* - ``"warn"``
* - ``"strict"``
- Documents do not have to pass validation. If the document fails
validation, the write operation logs the validation failure.
- **Default**. Apply validation rules to all inserts and all updates.
* - ``"moderate"``
- Apply validation rules to inserts and to updates on existing *valid*
documents. Do not apply rules to updates on existing *invalid*
documents.
interface: phpmethod
operation: MongoDB\\Database::createCollection
optional: true
position: 10
---
source:
file: apiargs-common-option.yaml
ref: maxTimeMS
operation: MongoDB\\Database::createCollection
position: 11
---
source:
file: apiargs-common-option.yaml
ref: typeMap
operation: MongoDB\\Database::createCollection
position: 12
position: 13
...
docs/includes/apiargs-MongoDBDatabase-method-createCollection-param.yaml
View file @ 6d4a1d31
......@@ -3,12 +3,12 @@ source:
ref: $collectionName
operation: MongoDB\\Database::createCollection
position: 1
optional: false
replacement:
action: " to create"
---
source:
file: apiargs-common-param.yaml
ref: $options
operation: MongoDB\\Database::createCollection
position: 2
optional: true
...
docs/includes/apiargs-MongoDBDatabase-method-drop-option.yaml
View file @ 6d4a1d31
source:
file: apiargs-common-option.yaml
ref: typeMap
operation: MongoDB\\Database::dropCollection
operation: MongoDB\\Database::drop
position: 1
description: |
Type map for BSON deserialization. This will be used for the returned command
result document. Defaults to the database's type map.
...
docs/includes/apiargs-MongoDBDatabase-method-drop-param.yaml
View file @ 6d4a1d31
source:
file: apiargs-common-param.yaml
ref: $collectionName
operation: MongoDB\\Database::dropCollection
position: 1
optional: false
---
source:
file: apiargs-common-param.yaml
ref: $options
operation: MongoDB\\Database::dropCollection
position: 2
optional: true
operation: MongoDB\\Database::drop
position: 1
...
docs/includes/apiargs-MongoDBDatabase-method-dropCollection-option.yaml
View file @ 6d4a1d31
......@@ -3,4 +3,7 @@ source:
ref: typeMap
operation: MongoDB\\Database::dropCollection
position: 1
description: |
Type map for BSON deserialization. This will be used for the returned command
result document. Defaults to the database's type map.
...
docs/includes/apiargs-MongoDBDatabase-method-dropCollection-param.yaml
View file @ 6d4a1d31
......@@ -3,12 +3,12 @@ source:
ref: $collectionName
operation: MongoDB\\Database::dropCollection
position: 1
optional: false
replacement:
action: " to drop"
---
source:
file: apiargs-common-param.yaml
ref: $options
operation: MongoDB\\Database::dropCollection
position: 2
optional: true
...
docs/includes/apiargs-MongoDBDatabase-method-get-param.yaml
View file @ 6d4a1d31
......@@ -3,4 +3,6 @@ source:
ref: $collectionName
operation: MongoDB\\Database::__get
position: 1
replacement:
action: " to select"
...
docs/includes/apiargs-MongoDBDatabase-method-listCollections-option.yaml
View file @ 6d4a1d31
source:
file: apiargs-common-option.yaml
ref: readConcern
arg_name: option
name: filter
type: array|object
description: |
Query by which to filter collections.
interface: phpmethod
operation: MongoDB\\Database::listCollections
optional: true
position: 1
---
source:
file: apiargs-common-option.yaml
ref: readPreference
ref: maxTimeMS
operation: MongoDB\\Database::listCollections
position: 2
---
source:
file: apiargs-common-option.yaml
ref: typeMap
operation: MongoDB\\Database::listCollections
position: 3
---
source:
file: apiargs-common-option.yaml
ref: writeConcern
operation: MongoDB\\Database::listCollections
position: 4
...
docs/includes/apiargs-MongoDBDatabase-method-listCollections-param.yaml
View file @ 6d4a1d31
......@@ -3,5 +3,4 @@ source:
ref: $options
operation: MongoDB\\Database::listCollections
position: 1
optional: true
...
docs/includes/apiargs-MongoDBDatabase-method-selectCollection-option.yaml
View file @ 6d4a1d31
......@@ -3,22 +3,33 @@ source:
ref: readConcern
operation: MongoDB\\Database::selectCollection
position: 1
replacement:
resource: "collection"
parent: "database"
---
source:
file: apiargs-common-option.yaml
ref: readPreference
operation: MongoDB\\Database::selectCollection
position: 2
replacement:
resource: "collection"
parent: "database"
---
source:
file: apiargs-common-option.yaml
ref: typeMap
operation: MongoDB\\Database::selectCollection
position: 3
replacement:
parent: "database"
---
source:
file: apiargs-common-option.yaml
ref: writeConcern
operation: MongoDB\\Database::selectCollection
position: 4
replacement:
resource: "collection"
parent: "database"
...
docs/includes/apiargs-MongoDBDatabase-method-selectCollection-param.yaml
View file @ 6d4a1d31
......@@ -3,7 +3,8 @@ source:
ref: $collectionName
operation: MongoDB\\Database::selectCollection
position: 1
optional: false
replacement:
action: " to select"
---
source:
file: apiargs-common-param.yaml
......
docs/includes/apiargs-MongoDBDatabase-method-withOptions-option.yaml
View file @ 6d4a1d31
......@@ -3,30 +3,30 @@ source:
ref: readConcern
operation: MongoDB\\Database::withOptions
description: |
The default read concern to use for database operations. Defaults
to the original Databases's specified read concern.
The default read concern to use for database operations. Defaults to the
original Databases's read concern.
---
source:
file: apiargs-common-option.yaml
ref: readPreference
operation: MongoDB\\Database::withOptions
description: |
The default read preference to use for database operations.
Defaults to the original Database's read preference.
The default read preference to use for database operations. Defaults to the
original Database's read preference.
---
source:
file: apiargs-common-option.yaml
ref: typeMap
operation: MongoDB\\Database::withOptions
description: |
Default type map for cursors and BSON documents. Defaults to the
original Database's type map value.
Default type map to use for converting BSON. Defaults to the original
Database's type map.
---
source:
file: apiargs-common-option.yaml
ref: writeConcern
operation: MongoDB\\Database::withOptions
description: |
The default write concern to use for database operations. Defaults
to the original Database's specified write concern.
The default write concern to use for database operations. Defaults to the
original Database's write concern.
...
docs/includes/apiargs-MongoDBDatabase-method-withOptions-param.yaml
View file @ 6d4a1d31
source:
ref: $options
file: apiargs-common-param.yaml
ref: $options
operation: MongoDB\\Database::withOptions
position: 1
...
docs/reference/class/MongoDBDatabase.txt
View file @ 6d4a1d31
......@@ -44,8 +44,8 @@ Methods
.. toctree::
:titlesonly:
/reference/method/MongoDBDatabase__get
/reference/method/MongoDBDatabase__construct
/reference/method/MongoDBDatabase__get
/reference/method/MongoDBDatabase-command
/reference/method/MongoDBDatabase-createCollection
/reference/method/MongoDBDatabase-drop
......
docs/reference/method/MongoDBDatabase-command.txt
View file @ 6d4a1d31
......@@ -13,7 +13,7 @@ MongoDB\\Database::command()
Definition
----------
.. phpmethod:: MongoDB\\Database::command
.. phpmethod:: MongoDB\\Database::command()
Execute a :manual:`command </reference/command>` on the database.
......@@ -21,100 +21,121 @@ Definition
function command($command, array $options = []): MongoDB\Driver\Cursor
:phpmethod:`MongoDB\\Database::command` has the following parameters:
:phpmethod:`MongoDB\\Database::command()` has the following parameters:
.. include:: /includes/apiargs/MongoDBDatabase-method-command-param.rst
``command`` supports the following options:
The ``$options`` parameter supports the following options:
.. include:: /includes/apiargs/MongoDBDatabase-method-command-option.rst
:returns:
A :php:`MongoDB\\Driver\\Cursor <class.mongodb-driver-cursor>` object.
Example
-------
The following operation creates a new user in the database using
the :dbcommand:`createUser` command:
The following example executes an :manual:`isMaster
</reference/command/isMaster>` command, which returns a cursor with a single
result document:
.. code-block:: php
<?php
$database = (new MongoDB\Client)->example;
$newUser = $database->command(
[
'createUser' => 'admin',
'pwd' => 'admin123',
'roles' => [
'readWrite'
]
]
);
$cursor = $database->command(['isMaster' => 1]);
var_dump($c->toArray()[0]);
The output would resemble::
object(MongoDB\Model\BSONDocument)#11 (1) {
["storage":"ArrayObject":private]=>
array(8) {
["ismaster"]=>
bool(true)
["maxBsonObjectSize"]=>
int(16777216)
["maxMessageSizeBytes"]=>
int(48000000)
["maxWriteBatchSize"]=>
int(1000)
["localTime"]=>
object(MongoDB\BSON\UTCDateTime)#3 (1) {
["milliseconds"]=>
string(13) "1477608046464"
}
["maxWireVersion"]=>
int(4)
["minWireVersion"]=>
int(0)
["ok"]=>
float(1)
}
}
The following example executes a :manual:`listCollections
</reference/command/listCollections>` command, which returns a cursor with
multiple result documents:
.. code-block:: php
<?php
$database = (new MongoDB\Client)->example;
$cursor = $database->command(['isMaster' => 1]);
var_dump($newUser);
var_dump($c->toArray());
The output would resemble::
object(MongoDB\Driver\Cursor)#10 (2) {
["cursor"]=>
array(17) {
["stamp"]=>
int(0)
["is_command"]=>
bool(true)
["sent"]=>
bool(true)
["done"]=>
bool(false)
["end_of_event"]=>
bool(false)
["in_exhaust"]=>
bool(false)
["has_fields"]=>
bool(false)
["query"]=>
object(stdClass)#9 (3) {
["createUser"]=>
string(5) "admin"
["pwd"]=>
string(8) "admin123"
["roles"]=>
array(1) {
array(3) {
[0]=>
string(9) "readWrite"
object(MongoDB\Model\BSONDocument)#11 (1) {
["storage":"ArrayObject":private]=>
array(2) {
["name"]=>
string(11) "restaurants"
["options"]=>
object(MongoDB\Model\BSONDocument)#3 (1) {
["storage":"ArrayObject":private]=>
array(0) {
}
}
["fields"]=>
object(stdClass)#3 (0) {
}
["read_preference"]=>
}
[1]=>
object(MongoDB\Model\BSONDocument)#13 (1) {
["storage":"ArrayObject":private]=>
array(2) {
["mode"]=>
int(1)
["tags"]=>
["name"]=>
string(5) "users"
["options"]=>
object(MongoDB\Model\BSONDocument)#12 (1) {
["storage":"ArrayObject":private]=>
array(0) {
}
}
}
}
[2]=>
object(MongoDB\Model\BSONDocument)#15 (1) {
["storage":"ArrayObject":private]=>
array(2) {
["name"]=>
string(6) "restos"
["options"]=>
object(MongoDB\Model\BSONDocument)#14 (1) {
["storage":"ArrayObject":private]=>
array(0) {
}
}
["flags"]=>
int(0)
["skip"]=>
int(0)
["limit"]=>
int(1)
["count"]=>
int(1)
["batch_size"]=>
int(0)
["ns"]=>
string(12) "example.$cmd"
["current_doc"]=>
object(stdClass)#8 (1) {
["ok"]=>
float(1)
}
}
["server_id"]=>
int(1)
}
.. seealso::
......@@ -122,4 +143,6 @@ The output would resemble::
- :doc:`/tutorial/commands`
- :manual:`Database Commands </reference/command>` in the
MongoDB manual
- :php:`MongoDB\\Driver\\Cursor <class.mongodb-driver-cursor>`
- :php:`MongoDB\\Driver\\Manager::executeCommand()
<manual/en/mongodb-driver-manager.executecommand.php>`
docs/reference/method/MongoDBDatabase-createCollection.txt
View file @ 6d4a1d31
......@@ -13,7 +13,7 @@ MongoDB\\Database::createCollection()
Definition
----------
.. phpmethod:: MongoDB\\Database::createCollection
.. phpmethod:: MongoDB\\Database::createCollection()
Explicitly creates a collection.
......@@ -21,37 +21,37 @@ Definition
function createCollection($collectionName, array $options = []): array|object
MongoDB creates collections implicitly when you first reference
the collection in a command, such as when inserting a document
into a new collection. You may also explicitly create a collection
with specific options using the ``createCollection()``
method, or using :dbcommand:`create` in the :program:`mongo` shell.
MongoDB creates collections implicitly when you first reference the
collection in a command, such as when inserting a document into a new
collection. You may also explicitly create a collection with specific options
using the :phpmethod:`MongoDB\\Database::createCollection()` method, or using
:manual:`db.createCollection() </reference/method/db.createCollection/>` in
the :program:`mongo` shell.
Explicitly creating collections enables you to create
:manual:`capped collections </core/capped-collections>`, specify
:manual:`document validation criteria </core/document-validation>`,
or configure your storage engine or indexing options.
:phpmethod:`MongoDB\\Database::createCollection` has the following
:phpmethod:`MongoDB\\Database::createCollection()` has the following
parameters:
.. include:: /includes/apiargs/MongoDBDatabase-method-createCollection-param.rst
The ``$options`` parameter accepts the following options:
The ``$options`` parameter supports the following options:
.. include:: /includes/apiargs/MongoDBDatabase-method-createCollection-option.rst
Note that not all options are available on all versions of MongoDB.
Document Validation, for example, was added in MongoDB 3.2;
similarly, the WiredTiger storage engine is available only for
MongoDB 3.0 and later. Refer to the :manual:`create command
</reference/command/create>` reference in the MongoDB manual for
compatibility considerations.
Note that not all options are available on all versions of MongoDB. Document
validation, for example, was added in MongoDB 3.2; similarly, the WiredTiger
storage engine is available only for MongoDB 3.0 and later. Refer to the
:manual:`create </reference/command/create>` command reference in the MongoDB
manual for compatibility considerations.
Output
------
:returns:
Returns the command result document as an array.
An array or object with the result document of the :manual:`create
</reference/command/create>` command.
Example
-------
......@@ -61,6 +61,8 @@ database with document validation criteria:
.. code-block:: php
<?php
$db = (new MongoDB\Client)->demo;
$result = $db->createCollection('users', [
......@@ -70,12 +72,11 @@ database with document validation criteria:
],
]);
var_dump($result);
The output would then resemble::
Object(MongoDB\Model\BSONDocument)#11 (1) {
object(MongoDB\Model\BSONDocument)#11 (1) {
["storage":"ArrayObject":private]=>
array(1) {
["ok"]=>
......@@ -85,5 +86,6 @@ The output would then resemble::
.. seealso::
:manual:`create </reference/command/create>` command reference in
the MongoDB manual
- :manual:`create </reference/command/create>` command reference in the MongoDB
manual
- :manual:`db.createCollection() </reference/method/db.createCollection/>`
docs/reference/method/MongoDBDatabase-drop.txt
View file @ 6d4a1d31
......@@ -13,27 +13,27 @@ MongoDB\\Database::drop()
Definition
----------
.. phpmethod:: MongoDB\\Database::drop
.. phpmethod:: MongoDB\\Database::drop()
Drops the database.
Drop the database.
.. code-block:: php
function dropCollection($collectionName, array $options = []): array|object
function drop(array $options = []): array|object
:phpmethod:`MongoDB\\Database::drop` has the following
parameters:
:phpmethod:`MongoDB\\Database::drop()` has the following parameters:
.. include:: /includes/apiargs/MongoDBDatabase-method-drop-param.rst
The ``$options`` parameter accepts the following options:
The ``$options`` parameter supports the following options:
.. include:: /includes/apiargs/MongoDBDatabase-method-drop-option.rst
Output
------
:returns:
Returns the command result document as an array.
An array or object with the result document of the :manual:`dropDatabase
</reference/command/dropDatabase>` command. The return type will depend on
the ``typeMap`` option.
Example
-------
......@@ -42,11 +42,12 @@ The following example drops the ``demo`` database:
.. code-block:: php
<?php
$db = (new MongoDB\Client)->demo;
$result = $db->drop();
var_dump($result);
The output would then resemble::
......@@ -63,6 +64,6 @@ The output would then resemble::
.. seealso::
- :phpmethod:`MongoDB\\Client::dropDatabase`
- :manual:`dropDatabase </reference/command/dropDatabase>` command
reference in the MongoDB manual
- :phpmethod:`MongoDB\\Client::dropDatabase()`
- :manual:`dropDatabase </reference/command/dropDatabase>` command reference
in the MongoDB manual
docs/reference/method/MongoDBDatabase-dropCollection.txt
View file @ 6d4a1d31
......@@ -13,7 +13,7 @@ MongoDB\\Database::dropCollection()
Definition
----------
.. phpmethod:: MongoDB\\Database::dropCollection
.. phpmethod:: MongoDB\\Database::dropCollection()
Drop a collection within the current database.
......@@ -21,33 +21,34 @@ Definition
function dropCollection($collectionName, array $options = []): array|object
:phpmethod:`MongoDB\\Database::dropCollection` has the following
:phpmethod:`MongoDB\\Database::dropCollection()` has the following
parameters:
.. include:: /includes/apiargs/MongoDBDatabase-method-dropCollection-param.rst
The ``$options`` parameter accepts the following options:
The ``$options`` parameter supports the following options:
.. include:: /includes/apiargs/MongoDBDatabase-method-dropCollection-option.rst
Output
------
:returns:
Returns the command result document as an array.
An array or object with the result document of the :manual:`drop
</reference/command/drop>` command. The return type will depend on
the ``typeMap`` option.
Example
-------
The following example drops the ``users`` collection in the ``demo``
database:
The following example drops the ``users`` collection in the ``demo`` database:
.. code-block:: php
<?php
$db = (new MongoDB\Client)->demo;
$result = $db->dropCollection('users');
var_dump($result);
The output would then resemble::
......@@ -66,6 +67,6 @@ The output would then resemble::
.. seealso::
- :phpmethod:`MongoDB\\Collection::drop`
- :manual:`drop </reference/command/drop>` command reference in
the MongoDB manual
- :phpmethod:`MongoDB\\Collection::drop()`
- :manual:`drop </reference/command/drop>` command reference in the MongoDB
manual
docs/reference/method/MongoDBDatabase-getDatabaseName.txt
View file @ 6d4a1d31
......@@ -13,27 +13,27 @@ MongoDB\\Database::getDatabaseName()
Definition
----------
.. phpmethod:: MongoDB\\Database::getDatabaseName
.. phpmethod:: MongoDB\\Database::getDatabaseName()
Drops the database.
Returns the name of this database.
.. code-block:: php
function getDatabaseName(): string
Output
------
:returns:
Returns the name of the database as a string.
The name of this database as a string.
Example
-------
The following example gets the name of the database from the ``$db``
variable:
The following example prints the name of a database object:
.. code-block:: php
<?php
$db = (new MongoDB\Client)->demo;
echo $db->getDatabaseName();
......
docs/reference/method/MongoDBDatabase-getManager.txt
View file @ 6d4a1d31
......@@ -17,7 +17,7 @@ Definition
Accessor for the
:php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>` used by this
:phpclass:`Client <MongoDB\\Database>`.
:phpclass:`Database <MongoDB\\Database>`.
.. code-block:: php
......
docs/reference/method/MongoDBDatabase-listCollections.txt
View file @ 6d4a1d31
......@@ -13,34 +13,33 @@ MongoDB\\Database::listCollections()
Definition
----------
.. phpmethod:: MongoDB\\Database::listCollections
.. phpmethod:: MongoDB\\Database::listCollections()
Returns information for all collections in this database.
.. code-block:: php
function listCollections(array $options=[]): MongoDB\Model\CollectionInfoIterator
function listCollections(array $options = []): MongoDB\Model\CollectionInfoIterator
:phpmethod:`MongoDB\\Database::listCollections` has the following
:phpmethod:`MongoDB\\Database::listCollections()` has the following
parameters:
.. include:: /includes/apiargs/MongoDBDatabase-method-listCollections-param.rst
The ``$options`` parameter accepts the following options:
The ``$options`` parameter supports the following options:
.. include:: /includes/apiargs/MongoDBDatabase-method-listCollections-option.rst
Output
------
:returns:
Returns information for all collections in the database. The elements
in the returned iterator are ``MongoDB\Model\CollectionInfo`` objects.
A traversable :phpclass:`MongoDB\\Model\CollectionInfoIterator`, which
contains an :phpclass:`MongoDB\\Model\CollectionInfo` object for each
collection in the database.
Example
-------
The following example lists all of the collections in the ``example``
database:
The following example lists all of the collections in the ``example`` database:
.. code-block:: php
......@@ -61,7 +60,7 @@ The output would then resemble::
array(0) {
}
}
object(MongoDB\Model\CollectionInfo)#11 (2) {
object(MongoDB\Model\CollectionInfo)#3 (2) {
["name"]=>
string(5) "users"
["options"]=>
......@@ -76,10 +75,46 @@ The output would then resemble::
}
}
.. seealso::
The following example lists all collections whose name starts with ``"rest"``
in the ``example`` database:
.. code-block:: php
<?php
$database = (new MongoDB\Client)->example;
$collections = $database->listCollections([
'filter' => [
'name' => new MongoDB\BSON\Regex('^rest.*'),
],
]);
foreach ($collections as $collectionInfo) {
var_dump($collectionInfo);
}
The output would then resemble::
object(MongoDB\Model\CollectionInfo)#3 (2) {
["name"]=>
string(11) "restaurants"
["options"]=>
array(0) {
}
}
object(MongoDB\Model\CollectionInfo)#3 (2) {
["name"]=>
string(6) "restos"
["options"]=>
array(0) {
}
}
- :manual:`listCollections </reference/command/listCollections`
command reference in the MongoDB manual.
.. seealso::
- MongoDB Specification `Enumerating Collections
- :manual:`listCollections </reference/command/listCollections` command
reference in the MongoDB manual
- `Enumerating Collections
<https://github.com/mongodb/specifications/blob/master/source/enumerate-collections.rst>`_
specification
docs/reference/method/MongoDBDatabase-selectCollection.txt
View file @ 6d4a1d31
......@@ -13,38 +13,54 @@ MongoDB\\Database::selectCollection()
Definition
----------
.. phpmethod:: MongoDB\\Database::selectCollection
.. phpmethod:: MongoDB\\Database::selectCollection()
Selects a collection within the database. The collection inherits
options such as read preference and type map from the Database object
unless otherwise specified in the ``$options`` parameter.
Selects a collection within the database.
.. code-block:: php
function selectCollection($collectionName, array $options = []): MongoDB\Collection
:phpmethod:`MongoDB\\Database::selectCollection` has the following
:phpmethod:`MongoDB\\Database::selectCollection()` has the following
parameters:
.. include:: /includes/apiargs/MongoDBDatabase-method-selectCollection-param.rst
The ``$options`` parameter accepts the following options:
The ``$options`` parameter supports the following options:
.. include:: /includes/apiargs/MongoDBDatabase-method-selectCollection-option.rst
Output
------
:returns:
Returns a :phpclass:`MongoDB\\Collection` object.
A :phpclass:`MongoDB\\Collection` object.
Behavior
--------
The selected collection inherits options such as read preference and type
mapping from the :phpclass:`Database <MongoDB\\Database>` object. Options may be
overridden via the ``$options`` parameter.
Example
-------
The following example selects the ``users`` collection in the ``demo`` database:
.. code-block:: php
<?php
$db = (new MongoDB\Client)->demo;
$collection = $db->selectCollection('demo', 'users');
The following example selects the ``users`` collection in the ``demo``
database with a custom read preference:
.. code-block:: php
<?php
$db = (new MongoDB\Client)->demo;
$users = $db->selectCollection(
......@@ -54,87 +70,8 @@ database with a custom read preference:
]
);
var_dump($users);
The output would then resemble::
object(MongoDB\Collection)#8 (7) {
["collectionName"]=>
string(5) "users"
["databaseName"]=>
string(4) "demo"
["manager"]=>
object(MongoDB\Driver\Manager)#2 (2) {
["uri"]=>
string(25) "mongodb://localhost:27017"
["cluster"]=>
array(1) {
[0]=>
array(11) {
["host"]=>
string(9) "localhost"
["port"]=>
int(27017)
["type"]=>
int(0)
["is_primary"]=>
bool(false)
["is_secondary"]=>
bool(false)
["is_arbiter"]=>
bool(false)
["is_hidden"]=>
bool(false)
["is_passive"]=>
bool(false)
["tags"]=>
array(0) {
}
["last_is_master"]=>
array(0) {
}
["round_trip_time"]=>
int(-1)
}
}
}
["readConcern"]=>
object(MongoDB\Driver\ReadConcern)#5 (1) {
["level"]=>
NULL
}
["readPreference"]=>
object(MongoDB\Driver\ReadPreference)#3 (2) {
["mode"]=>
int(2)
["tags"]=>
array(0) {
}
}
["typeMap"]=>
array(3) {
["array"]=>
string(23) "MongoDB\Model\BSONArray"
["document"]=>
string(26) "MongoDB\Model\BSONDocument"
["root"]=>
string(26) "MongoDB\Model\BSONDocument"
}
["writeConcern"]=>
object(MongoDB\Driver\WriteConcern)#7 (4) {
["w"]=>
NULL
["wmajority"]=>
bool(false)
["wtimeout"]=>
int(0)
["journal"]=>
NULL
}
}
.. seealso::
- :phpmethod:`MongoDB\\Collection::__construct`
- :phpmethod:`MongoDB\\Database::__get`
- :phpmethod:`MongoDB\\Database::__get()`
- :phpmethod:`MongoDB\\Client::selectCollection()`
- :phpmethod:`MongoDB\\Collection::__construct()`
docs/reference/method/MongoDBDatabase-withOptions.txt
View file @ 6d4a1d31
......@@ -4,10 +4,16 @@ MongoDB\\Database::withOptions()
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
Definition
----------
.. phpmethod:: MongoDB\\Database::withOptions
.. phpmethod:: MongoDB\\Database::withOptions()
Returns a clone of the Database object, but with different options.
......@@ -15,34 +21,34 @@ Definition
function withOptions(array $options = []): MongoDB\Database
:phpmethod:`MongoDB\\Database::withOptions` supports the
following parameter:
:phpmethod:`MongoDB\\Database::withOptions()` has the following parameters:
.. include:: /includes/apiargs/MongoDBCollection-method-withOptions-param.rst
.. include:: /includes/apiargs/MongoDBDatabase-method-withOptions-param.rst
The ``$options`` parameter supports the following options:
.. include:: /includes/apiargs/MongoDBCollection-method-withOptions-option.rst
.. include:: /includes/apiargs/MongoDBDatabase-method-withOptions-option.rst
:returns:
A :phpclass:`MongoDB\\Database` object.
Example
-------
The following example clones the ``$newDb`` Database object with read
preference ``RP_SECONDARY``.
The following example clones an existing Database object with a new read
preference:
.. code-block:: php
<?php
$database = new MongoDB\Client;
$db = (new MongoDB\Client)->demo;
$newDb = $database->withOptions('sample','restaurants');
$newCollection = $sourceCollection->withOptions([
$newDb = $db->withOptions([
'readPreference' => new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::RP_SECONDARY),
]);
.. seealso::
- :phpmethod:`MongoDB\\Collection::__construct`
- :phpmethod:`MongoDB\\Database::__construct()`
docs/reference/method/MongoDBDatabase__construct.txt
View file @ 6d4a1d31
......@@ -13,7 +13,7 @@ MongoDB\\Database::__construct()
Definition
----------
.. phpmethod:: MongoDB\\Database::__construct
.. phpmethod:: MongoDB\\Database::__construct()
Constructs a new :phpclass:`Database <MongoDB\\Database>` instance.
......@@ -25,16 +25,20 @@ Definition
.. include:: /includes/apiargs/MongoDBDatabase-method-construct-param.rst
:phpmethod:`MongoDB\\Database::__construct` supports the following
options:
The ``$options`` parameter supports the following options:
.. include:: /includes/apiargs/MongoDBDatabase-method-construct-option.rst
If you construct the Database explicitly, the Database inherits any
options from the ``Manager`` object. If you select the Database
from a :phpclass:`Client <MongoDB\\Client>` object, the Database
inherits its options from that object.
Behavior
--------
If you construct a Database explicitly, the Database inherits any options from
the :php:`MongoDB\\Driver\\Manager <class.mongodb-driver-manager>` object. If
you select the Database from a :phpclass:`Client <MongoDB\\Client>` object, the
Database inherits its options from that object.
.. seealso::
- :phpmethod:`MongoDB\\Database::withOptions`
- :phpmethod:`MongoDB\\Database::withOptions()`
- :phpmethod:`MongoDB\\Client::selectDatabase()`
- :phpmethod:`MongoDB\\Client::__get()`
docs/reference/method/MongoDBDatabase__get.txt
View file @ 6d4a1d31
......@@ -4,7 +4,6 @@ MongoDB\\Database::__get()
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
......@@ -14,25 +13,29 @@ MongoDB\\Database::__get()
Definition
----------
.. phpmethod:: MongoDB\\Database::__get($collectionName)
.. phpmethod:: MongoDB\\Database::__get()
Select a collection from the database.
Select a collection within the database.
.. code-block:: php
function __get($collectionName): MongoDB\Collection
:phpmethod:`MongoDB\\Database::__get` has the following parameters:
:phpmethod:`MongoDB\\Database::__get()` has the following parameters:
.. include:: /includes/apiargs/MongoDBDatabase-method-get-param.rst
:returns:
A :phpclass:`MongoDB\\Collection` object.
Behavior
--------
The selected database inherits options such as read preference and
type mapping from the :phpclass:`Database <MongoDB\\Database>` object.
If you wish to override any options, use the
:phpmethod:`MongoDB\\Database::selectCollection` method.
The selected collection inherits options such as read preference and type
mapping from the :phpclass:`Database <MongoDB\\Database>` object. If you wish to
override any options, use the :phpmethod:`MongoDB\\Database::selectCollection`
method.
.. note::
......@@ -40,7 +43,7 @@ If you wish to override any options, use the
``.``, use complex syntax, as in ``$database->{'that.database'}``.
Alternatively, :phpmethod:`MongoDB\\Database::selectCollection` supports
selecting databases whose names contain special characters.
selecting collections whose names contain special characters.
Examples
--------
......@@ -59,5 +62,6 @@ collections from the ``demo`` database:
.. seealso::
- :phpmethod:`MongoDB\\Database::selectCollection`
- :php:`Property Overloading <oop5.overloading>` in the PHP Manual.
- :phpmethod:`MongoDB\\Database::selectCollection()`
- :phpmethod:`MongoDB\\Client::selectCollection()`
- :php:`Property Overloading <oop5.overloading>` in the PHP Manual
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