Merge branch 'v1.1'

Author: jmikola

docs/reference/method/MongoDBCollection-findOneAndUpdate.txt

@@ -68,7 +68,7 @@ setting its building number to ``"761"``:
        [ '$set' => [ 'address.building' => '761' ]],
        [
            'projection' => [ 'address' => 1 ],
-           'returnDocument' => MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_AFTER
+           'returnDocument' => MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_AFTER,
        ]
    );
 

docs/tutorial.txt

@@ -6,6 +6,7 @@ Tutorials
 .. toctree::
 
    /tutorial/crud
+   /tutorial/collation
    /tutorial/commands
    /tutorial/decimal128
    /tutorial/gridfs

docs/tutorial/collation.txt

@@ -0,0 +1,373 @@
+=========
+Collation
+=========
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. versionadded:: 1.1
+
+Overview
+--------
+
+MongoDB 3.4 introduced support for :manual:`collations
+</manual/reference/collation/>`, which provide a set of rules to comply with the
+conventions of a particular language when comparing strings.
+
+For example, in Canadian French, the last accent in a given word determines the
+sorting order. Consider the following French words:
+
+.. code-block:: none
+
+   cote < coté < côte < côté
+
+The sort order using the Canadian French collation would result in the
+following:
+
+.. code-block:: none
+
+   cote < côte < coté < côté
+
+If collation is unspecified, MongoDB uses simple binary comparison for strings.
+As such, the sort order of the words would be:
+
+.. code-block:: none
+
+    cote < coté < côte < côté
+
+Usage
+-----
+
+You can specify a default collation for collections and indexes when they are
+created, or specify a collation for CRUD operations and aggregations. For
+operations that support collation, MongoDB uses the collection's default
+collation unless the operation specifies a different collation.
+
+Collation Parameters
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: php
+
+   'collation' => [
+       'locale' => <string>,
+       'caseLevel' => <boolean>,
+       'caseFirst' => <string>,
+       'strength' => <integer>,
+       'numericOrdering' => <boolean>,
+       'alternate' => <string>,
+       'maxVariable' => <string>,
+       'normalization' => <boolean>,
+       'backwards' => <boolean>,
+   ]
+
+The only required parameter is ``locale``, which the server parses as an `ICU
+format locale ID <http://userguide.icu-project.org/locale>`_. For example, set
+``locale`` to ``en_US`` to represent US English or ``fr_CA`` to represent
+Canadian French.
+
+For a complete description of the available parameters, see :manual:`Collation
+Document </reference/collation/#collation-document>` in the MongoDB manual.
+
+Assign a Default Collation to a Collection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following example creates a new collection called ``contacts`` on the
+``test`` database and assigns a default collation with the ``fr_CA`` locale.
+Specifying a collation when you create the collection ensures that all
+operations involving a query that are run against the ``contacts`` collection
+use the ``fr_CA`` collation, unless the query specifies another collation. Any
+indexes on the new collection also inherit the default collation, unless the
+creation command specifies another collation.
+
+.. code-block:: php
+
+   <?php
+
+   $database = (new MongoDB\Client)->test;
+
+   $database->createCollection('contacts', [
+       'collation' => ['locale' => 'fr_CA'],
+   ]);
+
+Assign a Collation to an Index
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To specify a collation for an index, use the ``collation`` option when you
+create the index.
+
+The following example creates an index on the ``name`` field of the
+``address_book`` collection, with the ``unique`` parameter enabled and a default
+collation with ``locale`` set to ``en_US``.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->address_book;
+
+   $collection->createIndex(
+       ['first_name' => 1],
+       [
+           'collation' => ['locale' => 'en_US'],
+           'unique' => true,
+       ]
+   );
+
+To use this index, make sure your queries also specify the same collation. The
+following query uses the above index:
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->address_book;
+
+   $cursor = $collection->find(
+       ['first_name' => 'Adam'],
+       [
+           'collation' => ['locale' => 'en_US'],
+       ]
+   );
+
+The following queries do **NOT** use the index. The first query uses no
+collation, and the second uses a collation with a different ``strength`` value
+than the collation on the index.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->address_book;
+
+   $cursor1 = $collection->find(['first_name' => 'Adam']);
+
+   $cursor2 = $collection->find(
+       ['first_name' => 'Adam'],
+       [
+           'collation' => [
+               'locale' => 'en_US',
+               'strength' => 2,
+           ],
+       ]
+   );
+
+Operations that Support Collation
+---------------------------------
+
+All reading, updating, and deleting methods support collation. Some examples are
+listed below.
+
+``find()`` with ``sort``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Individual queries can specify a collation to use when matching and sorting
+results. The following query and sort operation uses a German collation with the
+``locale`` parameter set to ``de``.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->contacts;
+
+   $cursor = $collection->find(
+       ['city' => 'New York'],
+       [
+           'collation' => ['locale' => 'de'],
+           'sort' => ['name' => 1],
+       ]
+   );
+
+``findOneAndUpdate()``
+~~~~~~~~~~~~~~~~~~~~~~
+
+A collection called ``names`` contains the following documents:
+
+.. code-block:: javascript
+
+   { "_id" : 1, "first_name" : "Hans" }
+   { "_id" : 2, "first_name" : "Gunter" }
+   { "_id" : 3, "first_name" : "Günter" }
+   { "_id" : 4, "first_name" : "Jürgen" }
+
+The following :phpmethod:`findOneAndUpdate()
+<MongoDB\\Collection::findOneAndUpdate>` operation on the collection does not
+specify a collation.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->names;
+
+   $document = $collection->findOneAndUpdate(
+       ['first_name' => ['$lt' =-> 'Gunter']],
+       ['$set' => ['verified' => true]]
+   );
+
+Because ``Gunter`` is lexically first in the collection, the above operation
+returns no results and updates no documents.
+
+Consider the same :phpmethod:`findOneAndUpdate()
+<MongoDB\\Collection::findOneAndUpdate>` operation but with a collation
+specified, which uses the locale ``de@collation=phonebook``.
+
+.. note::
+
+   Some locales have a ``collation=phonebook`` option available for use with
+   languages which sort proper nouns differently from other words. According to
+   the ``de@collation=phonebook`` collation, characters with umlauts come before
+   the same characters without umlauts.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->names;
+
+   $document = $collection->findOneAndUpdate(
+       ['first_name' => ['$lt' =-> 'Gunter']],
+       ['$set' => ['verified' => true]],
+       [
+           'collation' => ['locale' => 'de@collation=phonebook'],
+           'returnDocument' => MongoDB\Operation\FindOneAndUpdate::RETURN_DOCUMENT_AFTER,
+       ]
+   );
+
+The operation returns the following updated document:
+
+.. code-block:: javascript
+
+   { "_id" => 3, "first_name" => "Günter", "verified" => true }
+
+``findOneAndDelete()``
+~~~~~~~~~~~~~~~~~~~~~~
+
+Set the ``numericOrdering`` collation parameter to ``true`` to compare numeric
+strings by their numeric values.
+
+The collection ``numbers`` contains the following documents:
+
+.. code-block:: javascript
+
+   { "_id" : 1, "a" : "16" }
+   { "_id" : 2, "a" : "84" }
+   { "_id" : 3, "a" : "179" }
+
+The following example matches the first document in which field ``a`` has a
+numeric value greater than 100 and deletes it.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->numbers;
+
+   $document = $collection->findOneAndDelete(
+       ['a' => ['$gt' =-> '100']],
+       [
+           'collation' => [
+               'locale' => 'en',
+               'numericOrdering' => true,
+           ],
+       ]
+   );
+
+After the above operation, the following documents remain in the collection:
+
+.. code-block:: javascript
+
+   { "_id" : 1, "a" : "16" }
+   { "_id" : 2, "a" : "84" }
+
+If you perform the same operation without collation, the server deletes the
+first document it finds in which the lexical value of ``a`` is greater than
+``"100"``.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->numbers;
+
+   $document = $collection->findOneAndDelete(['a' => ['$gt' =-> '100']]);
+
+After the above operation is executed, the document in which ``a`` was equal to
+``"16"`` has been deleted, and the following documents remain in the collection:
+
+.. code-block:: javascript
+
+   { "_id" : 2, "a" : "84" }
+   { "_id" : 3, "a" : "179" }
+
+``deleteMany()``
+~~~~~~~~~~~~~~~~
+
+You can use collations with all the various CRUD operations which exist in the
+|php-library|.
+
+The collection ``recipes`` contains the following documents:
+
+.. code-block:: javascript
+
+   { "_id" : 1, "dish" : "veggie empanadas", "cuisine" : "Spanish" }
+   { "_id" : 2, "dish" : "beef bourgignon", "cuisine" : "French" }
+   { "_id" : 3, "dish" : "chicken molé", "cuisine" : "Mexican" }
+   { "_id" : 4, "dish" : "chicken paillard", "cuisine" : "french" }
+   { "_id" : 5, "dish" : "pozole verde", "cuisine" : "Mexican" }
+
+Setting the ``strength`` parameter of the collation document to ``1`` or ``2``
+causes the server to disregard case in the query filter. The following example
+uses a case-insensitive query filter to delete all records in which the
+``cuisine`` field matches ``French``.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->recipes;
+
+   $collection->deleteMany(
+       ['cuisine' => 'French'],
+       [
+           'collation' => [
+               'locale' => 'en_US',
+               'strength' => 1,
+           ],
+       ]
+   );
+
+After the above operation runs, the documents with ``_id`` values of ``2`` and
+``4`` are deleted from the collection.
+
+Aggregation
+~~~~~~~~~~~
+
+To use collation with an :phpmethod:`aggregate()
+<MongoDB\\Collection::aggregate>` operation, specify a collation in the
+aggregation options.
+
+The following aggregation example uses a collection called ``names`` and groups
+the ``first_name`` field together, counts the total number of results in each
+group, and sorts the results by German phonebook order.
+
+.. code-block:: php
+
+   <?php
+
+   $collection = (new MongoDB\Client)->test->recipes;
+
+   $cursor = $collection->aggregate(
+       [
+           ['$group' => ['_id' => '$first_name', 'name_count' => ['$sum' => 1]]],
+           ['$sort' => ['_id' => 1]],
+       ],
+       [
+           'collation' => ['locale' => 'de@collation=phonebook'],
+       ]
+   );