From dccc45ea43464c4da08220d19a80fa3089bca8e1 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 10:46:28 -0400 Subject: [PATCH 01/25] Format testing --- source/{monitoring.txt => logging-monitoring.txt} | 0 source/{monitoring => logging-monitoring}/cluster-monitoring.txt | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename source/{monitoring.txt => logging-monitoring.txt} (100%) rename source/{monitoring => logging-monitoring}/cluster-monitoring.txt (100%) diff --git a/source/monitoring.txt b/source/logging-monitoring.txt similarity index 100% rename from source/monitoring.txt rename to source/logging-monitoring.txt diff --git a/source/monitoring/cluster-monitoring.txt b/source/logging-monitoring/cluster-monitoring.txt similarity index 100% rename from source/monitoring/cluster-monitoring.txt rename to source/logging-monitoring/cluster-monitoring.txt From 8def9676be1f5e3977e924cd973ef444d2ecbe33 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 10:57:33 -0400 Subject: [PATCH 02/25] edit gh action --- .github/workflows/add-redirects.yml | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/.github/workflows/add-redirects.yml b/.github/workflows/add-redirects.yml index 88be78cd..8d9d8515 100644 --- a/.github/workflows/add-redirects.yml +++ b/.github/workflows/add-redirects.yml @@ -35,7 +35,7 @@ jobs: new=$(echo "$file" | cut -d',' -f2) new="${new#source}" new="${new%.txt}" - renamed_redirects+="[\\*-master]: \$\{prefix\}/\$\{version\}$old/ -> \$\{base\}/\$\{version\}$new/
" + renamed_redirects+="[\\-*]: \$\{prefix\}/\$\{version\}$old/ -> \$\{base\}/\$\{version\}$new/
" done if [ "$renamed_redirects" == "" ]; then renamed_redirects="No redirects to add" @@ -52,11 +52,14 @@ jobs: old=$(echo "$file" | cut -d',' -f1) old="${old#source}" old="${old%.txt}/" - deleted_redirects+="[\*-master]: \$\{prefix\}/\$\{version\}$old -> \$\{base\}/\$\{version\}\\n" + deleted_redirects+="[\\-*]: \$\{prefix\}/\$\{version\}$old -> \$\{base\}/\$\{version\}\\n" done - echo "${deleted_redirects}" + if [ "$deleted_redirects" == "" ]; then + deleted_redirects="No redirects to add" + fi + echo "redirects=${deleted_redirects}" >> "$GITHUB_OUTPUT" - name: Update the PR Description uses: MongoCaleb/pr-description-action@master with: - content: "\n- [ ] Did you add redirects for renamed files?\n${{ steps.renamed-files.outputs.redirects }}\n- [ ] Did you add redirects for deleted files?" + content: "\n- [ ] Did you add redirects?\n # Replace with earliest backport target version \n${{ steps.renamed-files.outputs.redirects }}${{ steps.deleted-files.outputs.redirects }}\n" token: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file From bbbc1c3d81b92f7a7bb02a261c906e0d99f35043 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:00:22 -0400 Subject: [PATCH 03/25] modify files --- .../change-streams.txt | 0 source/tutorial/commands.txt | 154 ------------------ 2 files changed, 154 deletions(-) rename source/{read => logging-monitoring}/change-streams.txt (100%) delete mode 100644 source/tutorial/commands.txt diff --git a/source/read/change-streams.txt b/source/logging-monitoring/change-streams.txt similarity index 100% rename from source/read/change-streams.txt rename to source/logging-monitoring/change-streams.txt diff --git a/source/tutorial/commands.txt b/source/tutorial/commands.txt deleted file mode 100644 index 4305e07a..00000000 --- a/source/tutorial/commands.txt +++ /dev/null @@ -1,154 +0,0 @@ -:orphan: - -========================= -Execute Database Commands -========================= - -.. meta:: - :description: Learn to execute database commands with the MongoDB PHP Library, including handling single and multiple result documents and setting custom read preferences. - - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -The |php-library| provides helper methods across the :phpclass:`Client -`, :phpclass:`Database `, and -:phpclass:`Collection ` classes for common -:manual:`database commands `. In addition, the -:phpmethod:`MongoDB\Database::command()` method may be used to run database -commands that do not have a helper method. - -The :phpmethod:`MongoDB\Database::command()` method always returns a -:php:`MongoDB\Driver\Cursor ` object, since it must -support execution of commands that return single result documents *and* multiple -results via a command cursor. - -Commands That Return a Single Result Document ---------------------------------------------- - -Most database commands return a single result document, which can be obtained by -converting the returned cursor to an array and accessing its first element. The -following example executes a :manual:`ping ` command -and prints its result document: - -.. code-block:: php - - test; - - $cursor = $database->command(['ping' => 1]); - - var_dump($cursor->toArray()[0]); - -The output would resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#11 (1) { - ["storage":"ArrayObject":private]=> - array(1) { - ["ok"]=> - float(1) - } - } - -Commands That Yield Multiple Results ------------------------------------- - -Some database commands return a cursor with multiple results. The following -example executes :manual:`listCollections `, -which returns a cursor containing a result document for each collection in the -``test`` database, and iterates through the results using a ``foreach`` loop. -Note that this example is illustrative; applications would generally use -:phpmethod:`MongoDB\Database::listCollections()` in practice. - -.. code-block:: php - - test; - - $cursor = $database->command(['listCollections' => 1]); - - foreach ($cursor as $collection) { - echo $collection['name'], "\n"; - } - -The output might resemble the following: - -.. code-block:: none - - persons - posts - zips - -.. note:: - - At the *protocol* level, commands that yield multiple results via a cursor - will return a single result document with the essential ingredients for - constructing the cursor (i.e. the cursor's ID, namespace, and an optional - first batch of results). If the :php:`MongoDB\Driver\Manager::executeCommand() - ` method in the extension detects - such a response, it will construct an iterable command cursor and return it - instead of the raw result document. If necessary, raw result documents can - still be observed using :php:`command monitoring - `. - -Specifying a Custom Read Preference ------------------------------------ - -Write commands, such as :manual:`createUser `, -can only be executed on a writable server (e.g. primary replica set -member). Command helper methods in the |php-library|, such as -:phpmethod:`MongoDB\Database::drop()`, know to apply their own :term:`read -preference` if necessary. However, the :phpmethod:`MongoDB\Database::command()` -method is a generic method and defaults to the read preference of the Database -object on which it is invoked. When necessary, the ``readPreference`` option may -be used to override the default read preference. - -The following example connects to a cluster and specifies ``secondaryPreferred`` -as the Client's default read preference. It then specifies a ``primary`` read -preference when executing the ``createUser`` command on the ``test`` database: - -.. code-block:: php - - 'secondaryPreferred'] - ); - - $client->test; - - $cursor = $db->command( - [ - 'createUser' => 'username', - 'pwd' => 'password', - 'roles' => ['readWrite'], - ], - [ - 'readPreference' => new MongoDB\Driver\ReadPreference('primary'), - ] - ); - - var_dump($cursor->toArray()[0]); - -The output would then resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#8 (1) { - ["storage":"ArrayObject":private]=> - array(1) { - ["ok"]=> - float(1) - } - } From c1eb94b477e639a130d49700ee400e93a0009dd9 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:06:17 -0400 Subject: [PATCH 04/25] edit --- .github/workflows/add-redirects.yml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/add-redirects.yml b/.github/workflows/add-redirects.yml index 8d9d8515..ea8da792 100644 --- a/.github/workflows/add-redirects.yml +++ b/.github/workflows/add-redirects.yml @@ -35,7 +35,8 @@ jobs: new=$(echo "$file" | cut -d',' -f2) new="${new#source}" new="${new%.txt}" - renamed_redirects+="[\\-*]: \$\{prefix\}/\$\{version\}$old/ -> \$\{base\}/\$\{version\}$new/
" + #single quotes = ${var} rendered literally; double quotes = $var interpreted + renamed_redirects+='
  • [\-*]: ${prefix}/${version}'"$old"'/ -> ${base}/${version}'"$new"'/
    • ' done if [ "$renamed_redirects" == "" ]; then renamed_redirects="No redirects to add" @@ -52,7 +53,7 @@ jobs: old=$(echo "$file" | cut -d',' -f1) old="${old#source}" old="${old%.txt}/" - deleted_redirects+="[\\-*]: \$\{prefix\}/\$\{version\}$old -> \$\{base\}/\$\{version\}\\n" + deleted_redirects+='
  • [\-*]: ${prefix}/${version}'"$old"'/ -> ${base}/${version}/
    • ' done if [ "$deleted_redirects" == "" ]; then deleted_redirects="No redirects to add" @@ -61,5 +62,5 @@ jobs: - name: Update the PR Description uses: MongoCaleb/pr-description-action@master with: - content: "\n- [ ] Did you add redirects?\n # Replace with earliest backport target version \n${{ steps.renamed-files.outputs.redirects }}${{ steps.deleted-files.outputs.redirects }}\n" + content: "\n- [ ] Did you add redirects?\n *Replace with earliest backport target version*\n${{ steps.renamed-files.outputs.redirects }}${{ steps.deleted-files.outputs.redirects }}\n" token: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file From 938dd3c2c7dea4dff50b9b9afab74f7e2f8f338c Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:08:35 -0400 Subject: [PATCH 05/25] delete --- source/tutorial/encryption.txt | 274 --------------------------------- 1 file changed, 274 deletions(-) delete mode 100644 source/tutorial/encryption.txt diff --git a/source/tutorial/encryption.txt b/source/tutorial/encryption.txt deleted file mode 100644 index 70b99df3..00000000 --- a/source/tutorial/encryption.txt +++ /dev/null @@ -1,274 +0,0 @@ -:orphan: - -================= -In-Use Encryption -================= - -.. meta:: - :description: Learn how to implement in-use encryption in PHP projects with the MongoDB PHP Library, including managing encryption keys and configuring client-side field level encryption. - - -.. contents:: On this page - :local: - :backlinks: none - :depth: 3 - :class: singlecol - - -Dependencies ------------- - -To get started using in-use encryption in your project, the -:php:`extension ` will need to be compiled with -`libmongocrypt `_ (enabled by -default). - -Additionally, either ``crypt_shared`` or ``mongocryptd`` are required in order to -use *automatic* client-side encryption. Neither is required for *explicit* -encryption. - -``crypt_shared`` -~~~~~~~~~~~~~~~~ - -The :manual:`Automatic Encryption Shared Library ` -(``crypt_shared``) provides the same functionality as ``mongocryptd``, but does not -require you to spawn another process to perform automatic encryption. - -By default, the extension attempts to load ``crypt_shared`` from the system -path(s) and uses it automatically if found. To load ``crypt_shared`` from -another location, use the ``cryptSharedLibPath`` auto encryption -:php:`driver option ` -when constructing a client. If the extension cannot load ``crypt_shared`` it -will attempt to fallback to using ``mongocryptd`` by default. The -``cryptSharedLibRequired`` option may be used to always require ``crypt_shared`` -and fail if it cannot be loaded. - -For detailed installation instructions see the MongoDB documentation for the -:manual:`Automatic Encryption Shared Library `. - -``mongocryptd`` -~~~~~~~~~~~~~~~ - -The ``mongocryptd`` binary is an alternative requirement for automatic client-side -encryption and is included as a component in the -:manual:`MongoDB Enterprise Server package `. -For detailed installation instructions see the -:manual:`MongoDB documentation on mongocryptd `. - -``mongocryptd`` performs the following: - -- Parses the automatic encryption rules specified in the client configuration. - If the ``schemaMap`` auto encryption driver option contains invalid syntax, - ``mongocryptd`` returns an error. - -- Uses the specified automatic encryption rules to mark fields in read and write - operations for encryption. - -- Rejects read/write operations that may return unexpected or incorrect results - when applied to an encrypted field. For supported and unsupported operations, - see :manual:`Supported Operations for Automatic Encryption `. - -A client configured with auto encryption will automatically spawn the -``mongocryptd`` process from the application's ``PATH``. Applications can control -the spawning behavior via various auto encryption -:php:`driver options `. - -``mongocryptd`` is only responsible for supporting automatic client-side encryption -and does not itself perform any encryption or decryption. - -Managing Encryption Keys ------------------------- - -.. seealso:: :manual:`Encryption Key Management ` in the MongoDB manual - -Creating an Encryption Key -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - The following examples use a local master key. While this is suitable for - development, a production application should use a supported cloud provider - (e.g. AWS KMS). The master key is used to encrypt locally stored data keys - and thus it is very important that you keep this key secure. - -To create an encryption key, create a -:php:`MongoDB\Driver\ClientEncryption ` -instance with encryption options and use the -:php:`createDataKey() ` -method. The method will return the key ID which can be used to reference the key -later. You can also pass multiple :ref:`alternate names ` for this key -and reference the key by these names instead of the key ID. - -Creating a new data encryption key would typically be done on initial -deployment, but depending on your use case you may want to use more than one -encryption key (e.g. user-specific encryption keys) or create them dynamically. - -.. literalinclude:: /examples/encryption/create_data_key.php - :language: php - -.. _alt_name: - -Referencing Encryption Keys by an Alternative Name -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To reference keys in your application, you can use the ``keyAltName`` -attribute specified when creating the key. The following example creates an -encryption key with an alternative name, which could be done when deploying the -application. The script then encrypts data by referencing the key by its -alternative name using the ``keyAltName`` option instead of ``keyId``. - -.. note:: - - Prior to adding a new key alternate name, you must create a partial, unique - index on the ``keyAltNames`` field. Client-Side Field Level Encryption - depends on server-enforced uniqueness of key alternate names. - -.. literalinclude:: /examples/encryption/key_alt_name.php - :language: php - - -Client-Side Field Level Encryption ----------------------------------- - -Introduced in MongoDB 4.2, -:manual:`Client-Side Field Level Encryption ` allows an -application to encrypt specific data fields in addition to pre-existing MongoDB -encryption features such as -:manual:`Encryption at Rest ` and -:manual:`TLS/SSL (Transport Encryption) `. - -With field level encryption, applications can encrypt fields in documents prior -to transmitting data over the wire to the server. Client-side field level -encryption supports workloads where applications must guarantee that -unauthorized parties, including server administrators, cannot read the encrypted -data. - - -Automatic Client-Side Field Level Encryption -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - Automatic client-side field level encryption requires MongoDB 4.2+ Enterprise - or a MongoDB 4.2+ Atlas cluster. - -Automatic client-side field level encryption is enabled by creating a client and -specifying the ``autoEncryption`` -:php:`driver option `. -The following examples demonstrate how to setup automatic client-side field -level encryption and use a -:php:`MongoDB\Driver\ClientEncryption ` -object to create a new encryption key. - - -.. _server-side: - -Server-Side Field Level Encryption Enforcement -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The MongoDB 4.2+ server supports using schema validation to enforce encryption -of specific fields in a collection. This schema validation will prevent an -application from inserting unencrypted values for any fields marked with the -:manual:`"encrypt" schema keyword `. - -The following example sets up a collection with automatic encryption using a -``$jsonSchema`` validator and -:manual:`Encryption Schema syntax `. -Data in the ``encryptedField`` field is automatically encrypted on insertion and -decrypted when reading on the client side. - -.. literalinclude:: /examples/encryption/csfle-automatic_encryption-server_side_schema.php - :language: php - - -Providing Local Automatic Encryption Rules -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following example uses the ``schemaMap`` auto encryption driver option to -define encrypted fields using a -:manual:`strict subset of the JSON schema syntax `. - -Using ``schemaMap`` in conjunction with a :ref:`server-side schema ` -provides more security than relying entirely on a schema obtained from the -server. It protects against a malicious server advertising a false schema, which -could trick the client into sending unencrypted data that should be encrypted. - -.. note:: - - Only :manual:`Encryption Schema syntax ` - can be used with the ``schemaMap`` option. Do not specify document validation - keywords in the automatic encryption rules. To define document validation - rules, configure :manual:`schema validation `. - -.. literalinclude:: /examples/encryption/csfle-automatic_encryption-local_schema.php - :language: php - - -Explicit Encryption -~~~~~~~~~~~~~~~~~~~ - -Explicit encryption is a MongoDB community feature and does not use -``crypt_shared`` or ``mongocryptd``. Explicit encryption is provided by the -:php:`MongoDB\Driver\ClientEncryption ` class. - -.. literalinclude:: /examples/encryption/csfle-explicit_encryption.php - :language: php - - -Explicit Encryption with Automatic Decryption -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Although automatic encryption requires MongoDB 4.2+ enterprise or a MongoDB 4.2+ -Atlas cluster, automatic *decryption* is supported for all users. To configure -automatic decryption without automatic encryption set the -``bypassAutoEncryption`` auto encryption -:php:`driver option ` -when constructing a client. - -.. literalinclude:: /examples/encryption/csfle-explicit_encryption_automatic_decryption.php - :language: php - - -Queryable Encryption --------------------- - -Introduced in MongoDB 7.0, -:manual:`Queryable Encryption ` is another -form of in-use encryption. Data is encrypted client-side. Queryable Encryption -supports indexed encrypted fields, which are further processed server-side. - - -Automatic Queryable Encryption -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - Automatic queryable encryption requires MongoDB 7.0+ Enterprise or a MongoDB - 7.0+ Atlas cluster. - -Automatic encryption in Queryable Encryption utilizes ``crypt_shared`` or -``mongocryptd`` to automatically encrypt and decrypt data client-side. The data -in the ``encryptedIndexed`` and ``encryptedUnindexed`` fields will be -automatically encrypted on insertion and decrypted when querying on the client -side. Additionally, it is possible to query on the ``encryptedIndexed`` field. - -.. literalinclude:: /examples/encryption/queryable_encryption-automatic.php - :language: php - - -Explicit Queryable Encryption -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - Explicit queryable encryption requires MongoDB 7.0+. - -Explicit encryption in Queryable Encryption is performed using the -:php:`MongoDB\Driver\ClientEncryption::encrypt() ` -and :php:`decrypt() ` methods. Although -values must be explicitly encrypted (e.g. insertions, query criteria), automatic -*decryption* for queries is possible by configuring ``encryptedFields`` on the -collection, as demonstrated in the following example: - -.. literalinclude:: /examples/encryption/queryable_encryption-explicit.php - :language: php From aad46f0d7f0a26883017f63166370d546d7c58d0 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:12:11 -0400 Subject: [PATCH 06/25] edit --- .github/workflows/add-redirects.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/add-redirects.yml b/.github/workflows/add-redirects.yml index ea8da792..e1a1d49f 100644 --- a/.github/workflows/add-redirects.yml +++ b/.github/workflows/add-redirects.yml @@ -36,7 +36,7 @@ jobs: new="${new#source}" new="${new%.txt}" #single quotes = ${var} rendered literally; double quotes = $var interpreted - renamed_redirects+='
  • [\-*]: ${prefix}/${version}'"$old"'/ -> ${base}/${version}'"$new"'/
    • ' + renamed_redirects+='
  • [\\-*]: ${prefix}/${version}'"$old"'/ -> ${base}/${version}'"$new"'/
    • ' done if [ "$renamed_redirects" == "" ]; then renamed_redirects="No redirects to add" @@ -52,8 +52,8 @@ jobs: for file in $DELETED_FILES; do old=$(echo "$file" | cut -d',' -f1) old="${old#source}" - old="${old%.txt}/" - deleted_redirects+='
  • [\-*]: ${prefix}/${version}'"$old"'/ -> ${base}/${version}/
    • ' + old="${old%.txt}" + deleted_redirects+='
  • [\\-*]: ${prefix}/${version}'"$old"'/ -> ${base}/${version}/
    • ' done if [ "$deleted_redirects" == "" ]; then deleted_redirects="No redirects to add" @@ -62,5 +62,5 @@ jobs: - name: Update the PR Description uses: MongoCaleb/pr-description-action@master with: - content: "\n- [ ] Did you add redirects?\n *Replace with earliest backport target version*\n${{ steps.renamed-files.outputs.redirects }}${{ steps.deleted-files.outputs.redirects }}\n" + content: "\n- [ ] Did you add redirects?\n *Replace \ with earliest backport target version*\n${{ steps.renamed-files.outputs.redirects }}${{ steps.deleted-files.outputs.redirects }}\n" token: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file From 9ec81cb3552341255c0d5acf7769e163a742a8d3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:13:22 -0400 Subject: [PATCH 07/25] add back --- source/tutorial/commands.txt | 154 +++++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 source/tutorial/commands.txt diff --git a/source/tutorial/commands.txt b/source/tutorial/commands.txt new file mode 100644 index 00000000..b36460b6 --- /dev/null +++ b/source/tutorial/commands.txt @@ -0,0 +1,154 @@ +:orphan: + +========================= +Execute Database Commands +========================= + +.. meta:: + :description: Learn to execute database commands with the MongoDB PHP Library, including handling single and multiple result documents and setting custom read preferences. + + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +The |php-library| provides helper methods across the :phpclass:`Client +`, :phpclass:`Database `, and +:phpclass:`Collection ` classes for common +:manual:`database commands `. In addition, the +:phpmethod:`MongoDB\Database::command()` method may be used to run database +commands that do not have a helper method. + +The :phpmethod:`MongoDB\Database::command()` method always returns a +:php:`MongoDB\Driver\Cursor ` object, since it must +support execution of commands that return single result documents *and* multiple +results via a command cursor. + +Commands That Return a Single Result Document +--------------------------------------------- + +Most database commands return a single result document, which can be obtained by +converting the returned cursor to an array and accessing its first element. The +following example executes a :manual:`ping ` command +and prints its result document: + +.. code-block:: php + + test; + + $cursor = $database->command(['ping' => 1]); + + var_dump($cursor->toArray()[0]); + +The output would resemble: + +.. code-block:: none + + object(MongoDB\Model\BSONDocument)#11 (1) { + ["storage":"ArrayObject":private]=> + array(1) { + ["ok"]=> + float(1) + } + } + +Commands That Yield Multiple Results +------------------------------------ + +Some database commands return a cursor with multiple results. The following +example executes :manual:`listCollections `, +which returns a cursor containing a result document for each collection in the +``test`` database, and iterates through the results using a ``foreach`` loop. +Note that this example is illustrative; applications would generally use +:phpmethod:`MongoDB\Database::listCollections()` in practice. + +.. code-block:: php + + test; + + $cursor = $database->command(['listCollections' => 1]); + + foreach ($cursor as $collection) { + echo $collection['name'], "\n"; + } + +The output might resemble the following: + +.. code-block:: none + + persons + posts + zips + +.. note:: + + At the *protocol* level, commands that yield multiple results via a cursor + will return a single result document with the essential ingredients for + constructing the cursor (i.e. the cursor's ID, namespace, and an optional + first batch of results). If the :php:`MongoDB\Driver\Manager::executeCommand() + ` method in the extension detects + such a response, it will construct an iterable command cursor and return it + instead of the raw result document. If necessary, raw result documents can + still be observed using :php:`command monitoring + `. + +Specifying a Custom Read Preference +----------------------------------- + +Write commands, such as :manual:`createUser `, +can only be executed on a writable server (e.g. primary replica set +member). Command helper methods in the |php-library|, such as +:phpmethod:`MongoDB\Database::drop()`, know to apply their own :term:`read +preference` if necessary. However, the :phpmethod:`MongoDB\Database::command()` +method is a generic method and defaults to the read preference of the Database +object on which it is invoked. When necessary, the ``readPreference`` option may +be used to override the default read preference. + +The following example connects to a cluster and specifies ``secondaryPreferred`` +as the Client's default read preference. It then specifies a ``primary`` read +preference when executing the ``createUser`` command on the ``test`` database: + +.. code-block:: php + + 'secondaryPreferred'] + ); + + $client->test; + + $cursor = $db->command( + [ + 'createUser' => 'username', + 'pwd' => 'password', + 'roles' => ['readWrite'], + ], + [ + 'readPreference' => new MongoDB\Driver\ReadPreference('primary'), + ] + ); + + var_dump($cursor->toArray()[0]); + +The output would then resemble: + +.. code-block:: none + + object(MongoDB\Model\BSONDocument)#8 (1) { + ["storage":"ArrayObject":private]=> + array(1) { + ["ok"]=> + float(1) + } + } \ No newline at end of file From 894b9cceb92638cdfed82bec121611a8fe51192e Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:16:06 -0400 Subject: [PATCH 08/25] check From 1957d57b28f61169615e8d8ea520fcfbea4e99c6 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:17:54 -0400 Subject: [PATCH 09/25] edits --- .github/workflows/add-redirects.yml | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/.github/workflows/add-redirects.yml b/.github/workflows/add-redirects.yml index e1a1d49f..cfc42121 100644 --- a/.github/workflows/add-redirects.yml +++ b/.github/workflows/add-redirects.yml @@ -38,9 +38,6 @@ jobs: #single quotes = ${var} rendered literally; double quotes = $var interpreted renamed_redirects+='
  • [\\-*]: ${prefix}/${version}'"$old"'/ -> ${base}/${version}'"$new"'/
    • ' done - if [ "$renamed_redirects" == "" ]; then - renamed_redirects="No redirects to add" - fi echo "redirects=${renamed_redirects}" >> "$GITHUB_OUTPUT" - name: Parse deleted files id: deleted-files @@ -55,12 +52,9 @@ jobs: old="${old%.txt}" deleted_redirects+='
  • [\\-*]: ${prefix}/${version}'"$old"'/ -> ${base}/${version}/
    • ' done - if [ "$deleted_redirects" == "" ]; then - deleted_redirects="No redirects to add" - fi echo "redirects=${deleted_redirects}" >> "$GITHUB_OUTPUT" - name: Update the PR Description uses: MongoCaleb/pr-description-action@master with: - content: "\n- [ ] Did you add redirects?\n *Replace \ with earliest backport target version*\n${{ steps.renamed-files.outputs.redirects }}${{ steps.deleted-files.outputs.redirects }}\n" + content: "\n- [ ] Did you add redirects?\n *Replace '' with earliest backport target version*\n${{ steps.renamed-files.outputs.redirects }}${{ steps.deleted-files.outputs.redirects }}\n" token: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file From 43fe55fedc370778d35803d19aff27a84a21d4f3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:16:06 -0400 Subject: [PATCH 10/25] check From 681ed0f1cf4a4fdedd349538524cb55aed512e08 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:18:42 -0400 Subject: [PATCH 11/25] check From efb119d23c7d32ce3bac00041ceaca28b6343ded Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:22:22 -0400 Subject: [PATCH 12/25] v format --- .github/workflows/add-redirects.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/add-redirects.yml b/.github/workflows/add-redirects.yml index cfc42121..5696d8db 100644 --- a/.github/workflows/add-redirects.yml +++ b/.github/workflows/add-redirects.yml @@ -36,7 +36,7 @@ jobs: new="${new#source}" new="${new%.txt}" #single quotes = ${var} rendered literally; double quotes = $var interpreted - renamed_redirects+='
  • [\\-*]: ${prefix}/${version}'"$old"'/ -> ${base}/${version}'"$new"'/
    • ' + renamed_redirects+='
  • [<v>-*]: ${prefix}/${version}'"$old"'/ -> ${base}/${version}'"$new"'/
    • ' done echo "redirects=${renamed_redirects}" >> "$GITHUB_OUTPUT" - name: Parse deleted files @@ -50,7 +50,7 @@ jobs: old=$(echo "$file" | cut -d',' -f1) old="${old#source}" old="${old%.txt}" - deleted_redirects+='
  • [\\-*]: ${prefix}/${version}'"$old"'/ -> ${base}/${version}/
    • ' + deleted_redirects+='
  • [<v>-*]: ${prefix}/${version}'"$old"'/ -> ${base}/${version}/
    • ' done echo "redirects=${deleted_redirects}" >> "$GITHUB_OUTPUT" - name: Update the PR Description From feb50696cacac5070399e32903ad4c9126bfde4c Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:16:06 -0400 Subject: [PATCH 13/25] check From 8d7fb5477b27a28f28300b0ce4da88f1a2116509 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:16:06 -0400 Subject: [PATCH 14/25] check From 5fab7a907a767dd771d9bb698e3edc49910a71e1 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:18:42 -0400 Subject: [PATCH 15/25] check From d385683dd38f245aac97e1001fb1caa9b705c7d7 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:22:44 -0400 Subject: [PATCH 16/25] check again From 9ae6426ebc53ce0a005a323f521dbbcb46635e63 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:26:17 -0400 Subject: [PATCH 17/25] format --- .github/workflows/add-redirects.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/add-redirects.yml b/.github/workflows/add-redirects.yml index 5696d8db..4dda7c0b 100644 --- a/.github/workflows/add-redirects.yml +++ b/.github/workflows/add-redirects.yml @@ -56,5 +56,5 @@ jobs: - name: Update the PR Description uses: MongoCaleb/pr-description-action@master with: - content: "\n- [ ] Did you add redirects?\n *Replace '' with earliest backport target version*\n${{ steps.renamed-files.outputs.redirects }}${{ steps.deleted-files.outputs.redirects }}\n" + content: "\n- [ ] Did you add redirects?\n *Replace <v> with earliest backport target version*\n${{ steps.renamed-files.outputs.redirects }}${{ steps.deleted-files.outputs.redirects }}\n" token: ${{ secrets.GITHUB_TOKEN }} \ No newline at end of file From 022894636ab78ec06b096069c0da0c8f45c2d626 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:16:06 -0400 Subject: [PATCH 18/25] check From 1a95522edf31c59864e93e0401b6acdf11958fa9 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:16:06 -0400 Subject: [PATCH 19/25] check From f76463bab831c1983e3934e5bd23401d1fbb0d8d Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:18:42 -0400 Subject: [PATCH 20/25] check From 468e44ed93148fadfeec14b06cce07bd112c70df Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:16:06 -0400 Subject: [PATCH 21/25] check From fc623a522b89b49f82db66d99d63174e0d6e95cc Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:16:06 -0400 Subject: [PATCH 22/25] check From f597711eab7ee9424d57a7c2c10382efb0330a2a Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:18:42 -0400 Subject: [PATCH 23/25] check From 5c622dd75fb1964840c34a7aea21a33e2b1b6097 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:22:44 -0400 Subject: [PATCH 24/25] check again From d9201366c37ad20d0e2017b6a467a71779a0a000 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:26:54 -0400 Subject: [PATCH 25/25] test --- source/tutorial/commands.txt | 154 ----------------------------------- 1 file changed, 154 deletions(-) delete mode 100644 source/tutorial/commands.txt diff --git a/source/tutorial/commands.txt b/source/tutorial/commands.txt deleted file mode 100644 index b36460b6..00000000 --- a/source/tutorial/commands.txt +++ /dev/null @@ -1,154 +0,0 @@ -:orphan: - -========================= -Execute Database Commands -========================= - -.. meta:: - :description: Learn to execute database commands with the MongoDB PHP Library, including handling single and multiple result documents and setting custom read preferences. - - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -The |php-library| provides helper methods across the :phpclass:`Client -`, :phpclass:`Database `, and -:phpclass:`Collection ` classes for common -:manual:`database commands `. In addition, the -:phpmethod:`MongoDB\Database::command()` method may be used to run database -commands that do not have a helper method. - -The :phpmethod:`MongoDB\Database::command()` method always returns a -:php:`MongoDB\Driver\Cursor ` object, since it must -support execution of commands that return single result documents *and* multiple -results via a command cursor. - -Commands That Return a Single Result Document ---------------------------------------------- - -Most database commands return a single result document, which can be obtained by -converting the returned cursor to an array and accessing its first element. The -following example executes a :manual:`ping ` command -and prints its result document: - -.. code-block:: php - - test; - - $cursor = $database->command(['ping' => 1]); - - var_dump($cursor->toArray()[0]); - -The output would resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#11 (1) { - ["storage":"ArrayObject":private]=> - array(1) { - ["ok"]=> - float(1) - } - } - -Commands That Yield Multiple Results ------------------------------------- - -Some database commands return a cursor with multiple results. The following -example executes :manual:`listCollections `, -which returns a cursor containing a result document for each collection in the -``test`` database, and iterates through the results using a ``foreach`` loop. -Note that this example is illustrative; applications would generally use -:phpmethod:`MongoDB\Database::listCollections()` in practice. - -.. code-block:: php - - test; - - $cursor = $database->command(['listCollections' => 1]); - - foreach ($cursor as $collection) { - echo $collection['name'], "\n"; - } - -The output might resemble the following: - -.. code-block:: none - - persons - posts - zips - -.. note:: - - At the *protocol* level, commands that yield multiple results via a cursor - will return a single result document with the essential ingredients for - constructing the cursor (i.e. the cursor's ID, namespace, and an optional - first batch of results). If the :php:`MongoDB\Driver\Manager::executeCommand() - ` method in the extension detects - such a response, it will construct an iterable command cursor and return it - instead of the raw result document. If necessary, raw result documents can - still be observed using :php:`command monitoring - `. - -Specifying a Custom Read Preference ------------------------------------ - -Write commands, such as :manual:`createUser `, -can only be executed on a writable server (e.g. primary replica set -member). Command helper methods in the |php-library|, such as -:phpmethod:`MongoDB\Database::drop()`, know to apply their own :term:`read -preference` if necessary. However, the :phpmethod:`MongoDB\Database::command()` -method is a generic method and defaults to the read preference of the Database -object on which it is invoked. When necessary, the ``readPreference`` option may -be used to override the default read preference. - -The following example connects to a cluster and specifies ``secondaryPreferred`` -as the Client's default read preference. It then specifies a ``primary`` read -preference when executing the ``createUser`` command on the ``test`` database: - -.. code-block:: php - - 'secondaryPreferred'] - ); - - $client->test; - - $cursor = $db->command( - [ - 'createUser' => 'username', - 'pwd' => 'password', - 'roles' => ['readWrite'], - ], - [ - 'readPreference' => new MongoDB\Driver\ReadPreference('primary'), - ] - ); - - var_dump($cursor->toArray()[0]); - -The output would then resemble: - -.. code-block:: none - - object(MongoDB\Model\BSONDocument)#8 (1) { - ["storage":"ArrayObject":private]=> - array(1) { - ["ok"]=> - float(1) - } - } \ No newline at end of file