DOCSP-47055: Collation (#258)

norareidy · web-flow · commit 96655abac865 · 2025-05-29T16:29:57.000-04:00
* DOCSP-47055: Collation

* add to each page

* edit

* edits

* list format

* SA feedback
diff --git a/source/crud/delete.txt b/source/crud/delete.txt
@@ -101,8 +101,8 @@ options you can set in the array:
 
    * - ``collation``
      - | Specifies the kind of language collation to use when comparing
-         strings. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
-         in the {+mdb-server+} manual.
+         strings. To learn more, see the :ref:`php-delete-collation` section
+         of this page.
 
    * - ``writeConcern``
      - | Sets the write concern for the operation. This option defaults to
@@ -132,6 +132,13 @@ options you can set in the array:
          fields </reference/command/delete/#command-fields>` guide in the
          {+mdb-server+} manual.
 
+.. _php-delete-collation:
+
+Collation
+~~~~~~~~~
+
+.. include:: /includes/collation.rst
+   
 Example
 ~~~~~~~
 
diff --git a/source/crud/query/count.txt b/source/crud/query/count.txt
@@ -120,7 +120,8 @@ describes some options you can set to customize the count operation:
      - Description
 
    * - ``collation``
-     - | The collation to use for the operation.
+     - | The collation to use for the operation. To learn more,
+         see the :ref:`php-count-collation` section of this page.
        | **Type**: ``array|object``
 
    * - ``hint``
@@ -166,6 +167,13 @@ operation to count a maximum of ``100`` results:
 
       Number of companies with 50 employees: 100
 
+.. _php-count-collation:
+
+Collation
+`````````
+
+.. include:: /includes/collation.rst
+
 .. _php-estimated-count:
 
 Retrieve an Estimated Count
diff --git a/source/crud/query/distinct.txt b/source/crud/query/distinct.txt
@@ -123,7 +123,8 @@ options you can set to customize the operation:
      - Description
 
    * - ``collation`` 
-     - | The collation to use for the operation.
+     - | The collation to use for the operation. To learn more, see the
+         :ref:`php-distinct-collation` section of this page.
        | **Type**: ``array|object``
 
    * - ``maxTimeMS``
@@ -169,6 +170,13 @@ in an options array to add a comment to the operation:
       "Angie'S Cafe Pizza"
       ...
 
+.. _php-distinct-collation:
+
+Collation
+`````````
+
+.. include:: /includes/collation.rst
+
 API Documentation
 -----------------
 
diff --git a/source/crud/query/retrieve.txt b/source/crud/query/retrieve.txt
@@ -190,7 +190,8 @@ you can set in the array:
 
    * - ``collation`` 
      - | The collation to use for the operation. The default value is the collation
-         specified for the collection.
+         specified for the collection. To learn more, see the :ref:`php-retrieve-collation`
+         section of this page.
        | **Type**: ``array|object``
 
    * - ``comment`` 
@@ -233,6 +234,13 @@ For a full list of options, see the API documentation for the
 `findOne() <{+api+}/method/MongoDBCollection-findOne/#parameters>`__ and 
 `find() <{+api+}/method/MongoDBCollection-find/#parameters>`__ parameters.
 
+.. _php-retrieve-collation:
+
+Collation
+`````````
+
+.. include:: /includes/collation.rst
+
 .. _php-retrieve-additional-information:
 
 Additional Information
diff --git a/source/crud/replace.txt b/source/crud/replace.txt
@@ -159,8 +159,8 @@ table describes some options you can set in the array:
 
    * - ``collation``
      - | Specifies the kind of language collation to use when sorting
-         results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
-         in the {+mdb-server+} manual.
+         results. To learn more, see the :ref:`php-replace-collation`
+         section of this page.
 
    * - ``hint``
      - | Gets or sets the index to scan for documents. 
@@ -182,6 +182,13 @@ table describes some options you can set in the array:
          fields </reference/command/insert/#command-fields>` guide in the
          {+mdb-server+} manual.
 
+.. _php-replace-collation:
+
+Collation
+~~~~~~~~~
+
+.. include:: /includes/collation.rst
+  
 Example
 ~~~~~~~
 
diff --git a/source/crud/update.txt b/source/crud/update.txt
@@ -125,8 +125,8 @@ describes some options you can set in the array:
 
    * - ``collation``
      - | Specifies the kind of language collation to use when sorting
-         results. For more information, see :manual:`Collation </reference/collation/#std-label-collation>`
-         in the {+mdb-server+} manual.
+         results. To learn more, see the :ref:`php-update-collation` section
+         of this page.
 
    * - ``arrayFilters``
      - | Specifies which array elements an update applies to if the operation modifies
@@ -166,6 +166,13 @@ match any existing documents.
    :language: php
    :dedent:
 
+.. _php-update-collation:
+
+Collation
+`````````
+
+.. include:: /includes/collation.rst
+
 Return Value
 ~~~~~~~~~~~~
 
diff --git a/source/includes/collation.rst b/source/includes/collation.rst
@@ -0,0 +1,97 @@
+To specify a collation for your operation, pass an ``$options`` array
+parameter that sets the ``collation`` option to the operation method.
+Assign the ``collation`` option to an array that configures the collation
+rules.
+
+The following table describes the fields you can set to configure
+the collation:
+
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Field
+     - Description
+
+   * - ``locale``
+     - | *(Required)* Specifies the International Components for Unicode (ICU) locale. For a
+         list of supported locales, see :manual:`Collation Locales and Default Parameters
+         </reference/collation-locales-defaults/#supported-languages-and-locales>`
+         in the {+mdb-server+} manual.
+       |
+       | **Data Type**: {+string-data-type+}
+
+   * - ``caseLevel``
+     - | *(Optional)* Specifies whether to include case comparison.
+       |
+       | When set to ``true``, the comparison behavior depends on the value of
+         the ``strength`` field:
+       |
+       | - If ``strength`` is ``1``, the {+library-short+} compares base
+       |   characters and case.
+       |
+       | - If ``strength`` is ``2``, the {+library-short+} compares base
+       |   characters, diacritics, other secondary differences, and case.
+       |
+       | - If ``strength`` is any other value, this field is ignored.
+       |
+       | When set to ``false``, the {+library-short+} doesn't include case comparison at
+         strength level ``1`` or ``2``.
+       |
+       | **Data Type**: {+bool-data-type+} 
+       | **Default**: ``false``
+
+   * - ``caseFirst``
+     - | *(Optional)* Specifies the sort order of case differences during tertiary
+         level comparisons.
+       |
+       | **Data Type**: {+string-data-type+} 
+       | **Default**: ``"off"``
+
+   * - ``strength``
+     - | *(Optional)* Specifies the level of comparison to perform, as defined in the
+         `ICU documentation <https://unicode-org.github.io/icu/userguide/collation/concepts.html#comparison-levels>`__.
+       |
+       | **Data Type**: {+int-data-type+} 
+       | **Default**: ``3``
+
+   * - ``numericOrdering``
+     - | *(Optional)* Specifies whether the driver compares numeric strings as numbers.
+       | 
+       | If set to ``true``, the {+library-short+} compares numeric strings as numbers.
+         For example, when comparing the strings "10" and "2", the library uses the
+         strings' numeric values and treats "10" as greater than "2".
+       |  
+       | If set to ``false``, the {+library-short+} compares numeric strings
+         as strings. For example, when comparing the strings "10" and "2", the library
+         compares one character at a time and treats "10" as less than "2".
+       |
+       | For more information, see :manual:`Collation Restrictions </reference/collation/#restrictions>`
+         in the {+mdb-server+} manual.
+       |
+       | **Data Type**: {+bool-data-type+}
+       | **Default**: ``false``
+
+   * - ``alternate``
+     - | *(Optional)* Specifies whether the library considers whitespace and punctuation as base
+         characters for comparison purposes.
+       |
+       | **Data Type**: {+string-data-type+}
+       | **Default**: ``"non-ignorable"``
+
+   * - ``maxVariable``
+     - | *(Optional)* Specifies which characters the library considers ignorable when
+         the ``alternate`` field is set to ``"shifted"``.
+       |
+       | **Data Type**: {+string-data-type+}
+       | **Default**: ``"punct"``
+
+   * - ``backwards``
+     - | *(Optional)* Specifies whether strings containing diacritics sort from the back of the string
+         to the front.
+       |
+       | **Data Type**: {+bool-data-type+} 
+       | **Default**: ``false``
+
+To learn more about collation and the possible values for each field, see the :manual:`Collation </reference/collation>`
+entry in the {+mdb-server+} manual.
diff --git a/source/monitoring-logging/change-streams.txt b/source/monitoring-logging/change-streams.txt
@@ -174,7 +174,8 @@ can set in the array:
        | This option is mutually exclusive with ``startAfter`` and ``resumeAfter``.
 
    * - ``collation``
-     - | Sets the collation to use for the change stream cursor.
+     - | Sets the collation to use for the change stream cursor. To learn more,
+         see the :ref:`php-change-stream-collation` section of this page.
 
 For a full list of ``watch()`` options, see `MongoDB\\Collection::watch()
 <{+api+}/method/MongoDBCollection-watch/>`__ in the API
@@ -255,6 +256,13 @@ output:
    :manual:`Change Streams with Document Pre- and Post-Images </changeStreams#change-streams-with-document-pre--and-post-images>` 
    in the {+mdb-server+} manual.
 
+.. _php-change-stream-collation:
+
+Collation
+~~~~~~~~~
+
+.. include:: /includes/collation.rst
+
 Additional Information
 ----------------------
 
