From 42fa4464eb70fb6f99b898878a6137ad52ba66e5 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:56:31 -0400 Subject: [PATCH 01/48] Test PR output --- 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 5993c51a8d57e62c4226f68d6ccecb624a568b39 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 11:57:34 -0400 Subject: [PATCH 02/48] check From cbac847e5d0c5920affe55c000f07826b0c6936a Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 12:10:12 -0400 Subject: [PATCH 03/48] check From 75f3081eb25c5c0145673dbdf2bad1488d8946b6 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 12:12:18 -0400 Subject: [PATCH 04/48] check From 75e8f5f997627aa8f0016e20080ef97c9c88aea0 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 12:13:09 -0400 Subject: [PATCH 05/48] delete --- 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 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 45b3669b7790956a9b3b4832c9b26213977ca53f Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 13:45:00 -0400 Subject: [PATCH 06/48] test rename --- REVIEWING.md => REVIEWING1.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename REVIEWING.md => REVIEWING1.md (100%) diff --git a/REVIEWING.md b/REVIEWING1.md similarity index 100% rename from REVIEWING.md rename to REVIEWING1.md From 281c2113e8a4d4465366c0a735085ad281642143 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 13:46:46 -0400 Subject: [PATCH 07/48] test --- REVIEWING1.md => REVIEWING.md | 0 .../connect/{client-cert-tabs.rst => client-cert-tabs1.rst} | 0 source/{read => logging-monitoring}/change-streams.txt | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename REVIEWING1.md => REVIEWING.md (100%) rename source/includes/connect/{client-cert-tabs.rst => client-cert-tabs1.rst} (100%) rename source/{read => logging-monitoring}/change-streams.txt (100%) diff --git a/REVIEWING1.md b/REVIEWING.md similarity index 100% rename from REVIEWING1.md rename to REVIEWING.md diff --git a/source/includes/connect/client-cert-tabs.rst b/source/includes/connect/client-cert-tabs1.rst similarity index 100% rename from source/includes/connect/client-cert-tabs.rst rename to source/includes/connect/client-cert-tabs1.rst 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 From 46d313034e15f4af1f54db7b52315f06ca9e3d81 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 13:51:07 -0400 Subject: [PATCH 08/48] test rst --- .../connect/{key-file-password.rst => key-file-password-temp.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/includes/connect/{key-file-password.rst => key-file-password-temp.rst} (100%) diff --git a/source/includes/connect/key-file-password.rst b/source/includes/connect/key-file-password-temp.rst similarity index 100% rename from source/includes/connect/key-file-password.rst rename to source/includes/connect/key-file-password-temp.rst From 7d0d31a11f35f286d16f0bdd62a9c39859f9271d Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 13:54:51 -0400 Subject: [PATCH 09/48] test rst again --- source/includes/connect/{crl-tabs.rst => crl-tabs-temp.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/includes/connect/{crl-tabs.rst => crl-tabs-temp.rst} (100%) diff --git a/source/includes/connect/crl-tabs.rst b/source/includes/connect/crl-tabs-temp.rst similarity index 100% rename from source/includes/connect/crl-tabs.rst rename to source/includes/connect/crl-tabs-temp.rst From 53a47a6075133981a3ff0a3cf1de06ede05e1edc Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 14:01:22 -0400 Subject: [PATCH 10/48] test --- .../connect/{key-file-password-temp.rst => key-file-password.rst} | 0 source/includes/connect/{ocsp-tabs.rst => ocsp-tabs-temp.rst} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename source/includes/connect/{key-file-password-temp.rst => key-file-password.rst} (100%) rename source/includes/connect/{ocsp-tabs.rst => ocsp-tabs-temp.rst} (100%) diff --git a/source/includes/connect/key-file-password-temp.rst b/source/includes/connect/key-file-password.rst similarity index 100% rename from source/includes/connect/key-file-password-temp.rst rename to source/includes/connect/key-file-password.rst diff --git a/source/includes/connect/ocsp-tabs.rst b/source/includes/connect/ocsp-tabs-temp.rst similarity index 100% rename from source/includes/connect/ocsp-tabs.rst rename to source/includes/connect/ocsp-tabs-temp.rst From d40d4e6d722006cca0119e4ea10980c1b7bbfe5c Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 14:04:21 -0400 Subject: [PATCH 11/48] fix --- .../connect/{insecure-tls-tabs.rst => insecure-tls-tabs-temp.rst} | 0 source/includes/connect/{ocsp-tabs-temp.rst => ocsp-tabs.rst} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename source/includes/connect/{insecure-tls-tabs.rst => insecure-tls-tabs-temp.rst} (100%) rename source/includes/connect/{ocsp-tabs-temp.rst => ocsp-tabs.rst} (100%) diff --git a/source/includes/connect/insecure-tls-tabs.rst b/source/includes/connect/insecure-tls-tabs-temp.rst similarity index 100% rename from source/includes/connect/insecure-tls-tabs.rst rename to source/includes/connect/insecure-tls-tabs-temp.rst diff --git a/source/includes/connect/ocsp-tabs-temp.rst b/source/includes/connect/ocsp-tabs.rst similarity index 100% rename from source/includes/connect/ocsp-tabs-temp.rst rename to source/includes/connect/ocsp-tabs.rst From b00921292fedcdf7b950abc3ac0ae028229c2cd4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 14:16:24 -0400 Subject: [PATCH 12/48] test rst --- .../includes/connect/{ca-file-tabs.rst => ca-file-tabs-temp.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/includes/connect/{ca-file-tabs.rst => ca-file-tabs-temp.rst} (100%) diff --git a/source/includes/connect/ca-file-tabs.rst b/source/includes/connect/ca-file-tabs-temp.rst similarity index 100% rename from source/includes/connect/ca-file-tabs.rst rename to source/includes/connect/ca-file-tabs-temp.rst From adb038d2270a43ec2fbfde1c83e86c2e6b5a3725 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 14:18:38 -0400 Subject: [PATCH 13/48] dont rename --- .../includes/connect/{ca-file-tabs-temp.rst => ca-file-tabs.rst} | 0 .../connect/{client-cert-tabs1.rst => client-cert-tabs.rst} | 0 source/includes/connect/{crl-tabs-temp.rst => crl-tabs.rst} | 0 .../connect/{insecure-tls-tabs-temp.rst => insecure-tls-tabs.rst} | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename source/includes/connect/{ca-file-tabs-temp.rst => ca-file-tabs.rst} (100%) rename source/includes/connect/{client-cert-tabs1.rst => client-cert-tabs.rst} (100%) rename source/includes/connect/{crl-tabs-temp.rst => crl-tabs.rst} (100%) rename source/includes/connect/{insecure-tls-tabs-temp.rst => insecure-tls-tabs.rst} (100%) diff --git a/source/includes/connect/ca-file-tabs-temp.rst b/source/includes/connect/ca-file-tabs.rst similarity index 100% rename from source/includes/connect/ca-file-tabs-temp.rst rename to source/includes/connect/ca-file-tabs.rst diff --git a/source/includes/connect/client-cert-tabs1.rst b/source/includes/connect/client-cert-tabs.rst similarity index 100% rename from source/includes/connect/client-cert-tabs1.rst rename to source/includes/connect/client-cert-tabs.rst diff --git a/source/includes/connect/crl-tabs-temp.rst b/source/includes/connect/crl-tabs.rst similarity index 100% rename from source/includes/connect/crl-tabs-temp.rst rename to source/includes/connect/crl-tabs.rst diff --git a/source/includes/connect/insecure-tls-tabs-temp.rst b/source/includes/connect/insecure-tls-tabs.rst similarity index 100% rename from source/includes/connect/insecure-tls-tabs-temp.rst rename to source/includes/connect/insecure-tls-tabs.rst From d7069ea45dfbbfc132f5c776ddafbd8ee5a46c4d Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 14:21:48 -0400 Subject: [PATCH 14/48] test outside source --- README.rst => README1.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename README.rst => README1.rst (100%) diff --git a/README.rst b/README1.rst similarity index 100% rename from README.rst rename to README1.rst From 044326ece8d386d8ef37d6dcd90c845955297790 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 14:31:41 -0400 Subject: [PATCH 15/48] test --- .../includes/connect/{ca-file-tabs.rst => ca-file-tabs-temp.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/includes/connect/{ca-file-tabs.rst => ca-file-tabs-temp.rst} (100%) diff --git a/source/includes/connect/ca-file-tabs.rst b/source/includes/connect/ca-file-tabs-temp.rst similarity index 100% rename from source/includes/connect/ca-file-tabs.rst rename to source/includes/connect/ca-file-tabs-temp.rst From 86c91e08439523e4b4ec508315ac58101a63d102 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 14:41:50 -0400 Subject: [PATCH 16/48] rename --- README1.rst => README2.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename README1.rst => README2.rst (100%) diff --git a/README1.rst b/README2.rst similarity index 100% rename from README1.rst rename to README2.rst From 698da10572535068dc4f55796db829e80e3d0617 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 15:04:47 -0400 Subject: [PATCH 17/48] test --- source/write/{delete.txt => delete-temp.txt} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/write/{delete.txt => delete-temp.txt} (100%) diff --git a/source/write/delete.txt b/source/write/delete-temp.txt similarity index 100% rename from source/write/delete.txt rename to source/write/delete-temp.txt From 3b352ba324a44e531f4f4713091ca9bea9b2609f Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 15:17:02 -0400 Subject: [PATCH 18/48] test rename --- source/connect/{tls.txt => tls-temp.txt} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/connect/{tls.txt => tls-temp.txt} (100%) diff --git a/source/connect/tls.txt b/source/connect/tls-temp.txt similarity index 100% rename from source/connect/tls.txt rename to source/connect/tls-temp.txt From e0b195ce98b21ccc2f197fb5ab7ac449ed4218c7 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 15:21:24 -0400 Subject: [PATCH 19/48] test --- source/write/{gridfs.txt => gridfs-temp.txt} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/write/{gridfs.txt => gridfs-temp.txt} (100%) diff --git a/source/write/gridfs.txt b/source/write/gridfs-temp.txt similarity index 100% rename from source/write/gridfs.txt rename to source/write/gridfs-temp.txt From 09ce66426a2f884c63607f84a6478381664a9aba Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 15:39:17 -0400 Subject: [PATCH 20/48] delete --- source/tutorial/server-selection.txt | 196 --------------------------- 1 file changed, 196 deletions(-) delete mode 100644 source/tutorial/server-selection.txt diff --git a/source/tutorial/server-selection.txt b/source/tutorial/server-selection.txt deleted file mode 100644 index 62c20cae..00000000 --- a/source/tutorial/server-selection.txt +++ /dev/null @@ -1,196 +0,0 @@ -:orphan: - -=============================== -Server Selection and Monitoring -=============================== - -.. meta:: - :description: Understand how the MongoDB PHP Library selects and monitors servers, including connection string options for server selection and monitoring. - - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Server Selection and Monitoring -------------------------------- - -Before any operation can be executed, the |php-library| must first select a -server from the topology (e.g. replica set, sharded cluster). Selecting a server -requires an accurate view of the topology, so the extension regularly monitors -the servers to which it is connected. - -In most other drivers, server discovery and monitoring is handled by a -background thread; however, the PHP driver is single-threaded and must therefore -perform monitoring *between* operations initiated by the application. - -Consider the following example application: - -.. code-block:: php - - test; - - /** - * The library creates an internal object for this operation and must select - * a server to use for executing that operation. - * - * If this is the first operation on the underlying libmongoc client, it must - * first discover the topology. It does so by establishing connections to any - * host(s) in the seed list (this may entail TLS and OCSP verification) and - * issuing "hello" commands. - * - * In the case of a replica set, connecting to a single host in the seed list - * should allow the driver to discover all other members in the replica set. - * In the case of a sharded cluster, the driver will start with an initial - * seed list of mongos hosts and, if SRV polling is utilized, may discover - * additional mongos hosts over time. - * - * If the topology was already initialized (i.e. this is not the first - * operation on the client), the driver may still need to perform monitoring - * (i.e. "hello" commands) and refresh its view of the topology. This process - * may entail adding or removing hosts from the topology. - * - * Once the topology has been discovered and any necessary monitoring has - * been performed, the driver may select a server according to the rules - * outlined in the server selection specification (e.g. applying a read - * preference, filtering hosts by latency). - */ - $database->command(['ping' => 1]); - -Although the application consists of only a few lines of PHP, there is actually -quite a lot going on behind the scenes! Interested readers can find this process -discussed in greater detail in the following documents: - -- `Single-threaded Mode `_ in the libmongoc documentation -- `Server Discovery and Monitoring `_ specification -- `Server Selection `_ specification - -Connection String Options -------------------------- - -There are several connection string options relevant to server selection and -monitoring. - -connectTimeoutMS -~~~~~~~~~~~~~~~~ - -``connectTimeoutMS`` specifies the limit for both establishing a connection to -a server *and* the socket timeout for server monitoring (``hello`` commands). -This defaults to 10 seconds for single-threaded drivers such as PHP. - -When a server times out during monitoring, it will not be re-checked until at -least five seconds -(`cooldownMS `_) -have elapsed. This timeout is intended to avoid having single-threaded drivers -block for ``connectTimeoutMS`` on *each* subsequent scan after an error. - -Applications can consider setting this option to slightly more than the greatest -latency among servers in the cluster. For example, if the greatest ``ping`` time -between the PHP application server and a database server is 200ms, it may be -reasonable to specify a timeout of one second. This would allow ample time for -establishing a connection and monitoring an accessible server, while also -significantly reducing the time to detect an inaccessible server. - -heartbeatFrequencyMS -~~~~~~~~~~~~~~~~~~~~ - -``heartbeatFrequencyMS`` determines how often monitoring should occur. This -defaults to 60 seconds for single-threaded drivers and can be set as low as -500ms. - -serverSelectionTimeoutMS -~~~~~~~~~~~~~~~~~~~~~~~~ - -``serverSelectionTimeoutMS`` determines the maximum amount of time to spend in -the server selection loop. This defaults to 30 seconds, but applications will -typically fail sooner if ``serverSelectionTryOnce`` is ``true`` and a smaller -``connectTimeoutMS`` value is in effect. - -The original default was established at a time when replica set elections took -much longer to complete. Applications can consider setting this option to -slightly more than the expected completion time for an election. For example, -:manual:`Replica Set Elections ` states that -elections will not typically exceed 12 seconds, so a 15-second timeout may be -reasonable. Applications connecting to a sharded cluster may consider a smaller -value still, since ``mongos`` insulates the driver from elections. - -That said, ``serverSelectionTimeoutMS`` should generally not be set to a value -smaller than ``connectTimeoutMS``. - -serverSelectionTryOnce -~~~~~~~~~~~~~~~~~~~~~~ - -``serverSelectionTryOnce`` determines whether the driver should give up after -the first failed server selection attempt or continue waiting until -``serverSelectionTimeoutMS`` is reached. PHP defaults to ``true``, which allows -the driver to "fail fast" when a server cannot be selected (e.g. no primary -during a failover). - -The default behavior is generally desirable for a high-traffic web applications, -as it means the worker process will not be blocked in a server selection loop -and can instead return an error response and immediately go on to serve another -request. Additionally, other driver features such as retryable reads and writes -can still enable applications to avoid transient errors such as a failover. - -That said, applications that prioritize resiliency over response time (and -worker pool utilization) may want to specify ``false`` for -``serverSelectionTryOnce``. - -socketCheckIntervalMS -~~~~~~~~~~~~~~~~~~~~~ - -``socketCheckIntervalMS`` determines how often a socket should be checked (using -a ``ping`` command) if it has not been used recently. This defaults to 5 seconds -and is intentionally lower than ``heartbeatFrequencyMS`` to better allow -single-threaded drivers to recover dropped connections. - -socketTimeoutMS -~~~~~~~~~~~~~~~ - -``socketTimeoutMS`` determines the maximum amount of time to spend reading or -writing to a socket. Since server monitoring uses ``connectTimeoutMS`` for its -socket timeouts, ``socketTimeoutMS`` only applies to operations executed by the -application. - -``socketTimeoutMS`` defaults to 5 minutes; however, it's likely that a PHP web -request would be terminated sooner due to -`max_execution_time `_, -which defaults to 30 seconds for web SAPIs. In a CLI environment, where -``max_execution_time`` is unlimited by default, it is more likely that -``socketTimeoutMS`` could be reached. - -.. note:: - - ``socketTimeoutMS`` is not directly related to server selection and - monitoring; however, it is frequently associated with the other options and - therefore bears mentioning. From 45e4afc4525cbd85576331454794aa259ed1c98e Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 15:41:32 -0400 Subject: [PATCH 21/48] rename --- source/connect/{tls-temp.txt => tls.txt} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/connect/{tls-temp.txt => tls.txt} (100%) diff --git a/source/connect/tls-temp.txt b/source/connect/tls.txt similarity index 100% rename from source/connect/tls-temp.txt rename to source/connect/tls.txt From e715ea52777e657503d037eeac86517491a7d4c4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 16:11:27 -0400 Subject: [PATCH 22/48] test --- source/connect/{tls.txt => tls-temp.txt} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/connect/{tls.txt => tls-temp.txt} (100%) diff --git a/source/connect/tls.txt b/source/connect/tls-temp.txt similarity index 100% rename from source/connect/tls.txt rename to source/connect/tls-temp.txt From bdafd69125a1267c0091191d26a1bb52b1ba2376 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 16:13:03 -0400 Subject: [PATCH 23/48] test outside source --- README2.rst => README3.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename README2.rst => README3.rst (100%) diff --git a/README2.rst b/README3.rst similarity index 100% rename from README2.rst rename to README3.rst From 14371d1e7c246d32cfc1ecd8f4ccc026ad26f69b Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 16:16:42 -0400 Subject: [PATCH 24/48] test --- source/includes/connect/{crl-tabs.rst => crl-tabs-temp.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/includes/connect/{crl-tabs.rst => crl-tabs-temp.rst} (100%) diff --git a/source/includes/connect/crl-tabs.rst b/source/includes/connect/crl-tabs-temp.rst similarity index 100% rename from source/includes/connect/crl-tabs.rst rename to source/includes/connect/crl-tabs-temp.rst From 62f33be39470e25c194f20645b8aed8cc0c22eef Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 16:18:00 -0400 Subject: [PATCH 25/48] test --- REVIEWING.md => REVIEWING1.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename REVIEWING.md => REVIEWING1.md (100%) diff --git a/REVIEWING.md b/REVIEWING1.md similarity index 100% rename from REVIEWING.md rename to REVIEWING1.md From 95e985a9be02fb77d8b912a91be5e83ba6887325 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 13 May 2025 16:37:29 -0400 Subject: [PATCH 26/48] edits --- source/connect/{tls-temp.txt => tls.txt} | 0 source/write/{delete-temp.txt => delete.txt} | 0 source/write/{gridfs-temp.txt => gridfs.txt} | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename source/connect/{tls-temp.txt => tls.txt} (100%) rename source/write/{delete-temp.txt => delete.txt} (100%) rename source/write/{gridfs-temp.txt => gridfs.txt} (100%) diff --git a/source/connect/tls-temp.txt b/source/connect/tls.txt similarity index 100% rename from source/connect/tls-temp.txt rename to source/connect/tls.txt diff --git a/source/write/delete-temp.txt b/source/write/delete.txt similarity index 100% rename from source/write/delete-temp.txt rename to source/write/delete.txt diff --git a/source/write/gridfs-temp.txt b/source/write/gridfs.txt similarity index 100% rename from source/write/gridfs-temp.txt rename to source/write/gridfs.txt From d0952b447c2be3925fb6204fabcdf0c7a566cdf3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 15 May 2025 16:53:51 -0400 Subject: [PATCH 27/48] edits --- README3.rst => README.rst | 0 REVIEWING1.md => REVIEWING.md | 0 source/includes/connect/{crl-tabs-temp.rst => crl-tabs.rst} | 0 source/{logging-monitoring => read}/change-streams.txt | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename README3.rst => README.rst (100%) rename REVIEWING1.md => REVIEWING.md (100%) rename source/includes/connect/{crl-tabs-temp.rst => crl-tabs.rst} (100%) rename source/{logging-monitoring => read}/change-streams.txt (100%) diff --git a/README3.rst b/README.rst similarity index 100% rename from README3.rst rename to README.rst diff --git a/REVIEWING1.md b/REVIEWING.md similarity index 100% rename from REVIEWING1.md rename to REVIEWING.md diff --git a/source/includes/connect/crl-tabs-temp.rst b/source/includes/connect/crl-tabs.rst similarity index 100% rename from source/includes/connect/crl-tabs-temp.rst rename to source/includes/connect/crl-tabs.rst diff --git a/source/logging-monitoring/change-streams.txt b/source/read/change-streams.txt similarity index 100% rename from source/logging-monitoring/change-streams.txt rename to source/read/change-streams.txt From 9fd9d333819d89f17184688e860289907e6baac5 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 15 May 2025 17:02:02 -0400 Subject: [PATCH 28/48] test --- source/{logging-monitoring.txt => monitoring.txt} | 0 source/{logging-monitoring => monitoring}/cluster-monitoring.txt | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename source/{logging-monitoring.txt => monitoring.txt} (100%) rename source/{logging-monitoring => monitoring}/cluster-monitoring.txt (100%) diff --git a/source/logging-monitoring.txt b/source/monitoring.txt similarity index 100% rename from source/logging-monitoring.txt rename to source/monitoring.txt diff --git a/source/logging-monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt similarity index 100% rename from source/logging-monitoring/cluster-monitoring.txt rename to source/monitoring/cluster-monitoring.txt From 969d28d672b026940710e2bc16e76a74987f8bb2 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 15 May 2025 17:03:22 -0400 Subject: [PATCH 29/48] 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 eba57e4673bd36d6717dcedf3d564338b789e0cd Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 15 May 2025 17:05:15 -0400 Subject: [PATCH 30/48] test --- .../includes/connect/{ca-file-tabs-temp.rst => ca-file-tabs.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/includes/connect/{ca-file-tabs-temp.rst => ca-file-tabs.rst} (100%) diff --git a/source/includes/connect/ca-file-tabs-temp.rst b/source/includes/connect/ca-file-tabs.rst similarity index 100% rename from source/includes/connect/ca-file-tabs-temp.rst rename to source/includes/connect/ca-file-tabs.rst From daa90bdb98c92fca3980915afa5ceb96e59b1fae Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 15 May 2025 17:11:53 -0400 Subject: [PATCH 31/48] rename 3 files --- source/{data-formats.txt => data-formats-temp.txt} | 0 source/{faq.txt => faq-temp.txt} | 0 source/{reference.txt => reference-temp.txt} | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename source/{data-formats.txt => data-formats-temp.txt} (100%) rename source/{faq.txt => faq-temp.txt} (100%) rename source/{reference.txt => reference-temp.txt} (100%) diff --git a/source/data-formats.txt b/source/data-formats-temp.txt similarity index 100% rename from source/data-formats.txt rename to source/data-formats-temp.txt diff --git a/source/faq.txt b/source/faq-temp.txt similarity index 100% rename from source/faq.txt rename to source/faq-temp.txt diff --git a/source/reference.txt b/source/reference-temp.txt similarity index 100% rename from source/reference.txt rename to source/reference-temp.txt From c0576587ead6c97fdb2e4f2aff0b7f4fd45997e5 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 10:15:34 -0400 Subject: [PATCH 32/48] test --- source/{read => monitoring}/change-streams.txt | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/{read => monitoring}/change-streams.txt (100%) diff --git a/source/read/change-streams.txt b/source/monitoring/change-streams.txt similarity index 100% rename from source/read/change-streams.txt rename to source/monitoring/change-streams.txt From 0471fd1e2aadec8ffcfa06bf81a02350fc601d7c Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 10:19:06 -0400 Subject: [PATCH 33/48] dup test --- config/redirects | 1 + 1 file changed, 1 insertion(+) diff --git a/config/redirects b/config/redirects index d437be97..c2d27f44 100644 --- a/config/redirects +++ b/config/redirects @@ -23,6 +23,7 @@ symlink: current -> v2.0 [v1.20-*]: ${prefix}/${version}/tutorial/crud/ -> ${base}/${version}/read/ [v1.20-*]: ${prefix}/${version}/tutorial/codecs/ -> ${base}/${version}/data-formats/codecs/ [v1.20-*]: ${prefix}/${version}/tutorial/collation/ -> ${base}/${version}/ +[v1.20-*]: ${prefix}/${version}/tutorial/crud/ -> ${base}/${version}/read/ [v1.20-*]: ${prefix}/${version}/tutorial/commands/ -> ${base}/${version}/run-command/ [v1.20-*]: ${prefix}/${version}/tutorial/custom-types/ -> ${base}/${version}/data-formats/custom-types/ [v1.20-*]: ${prefix}/${version}/tutorial/decimal128/ -> ${base}/${version}/data-formats/decimal128/ From b2a89d14e2e719b7b5f977c0dfda2403a8cb05e3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 10:34:30 -0400 Subject: [PATCH 34/48] remove dup --- config/redirects | 1 - 1 file changed, 1 deletion(-) diff --git a/config/redirects b/config/redirects index c2d27f44..d437be97 100644 --- a/config/redirects +++ b/config/redirects @@ -23,7 +23,6 @@ symlink: current -> v2.0 [v1.20-*]: ${prefix}/${version}/tutorial/crud/ -> ${base}/${version}/read/ [v1.20-*]: ${prefix}/${version}/tutorial/codecs/ -> ${base}/${version}/data-formats/codecs/ [v1.20-*]: ${prefix}/${version}/tutorial/collation/ -> ${base}/${version}/ -[v1.20-*]: ${prefix}/${version}/tutorial/crud/ -> ${base}/${version}/read/ [v1.20-*]: ${prefix}/${version}/tutorial/commands/ -> ${base}/${version}/run-command/ [v1.20-*]: ${prefix}/${version}/tutorial/custom-types/ -> ${base}/${version}/data-formats/custom-types/ [v1.20-*]: ${prefix}/${version}/tutorial/decimal128/ -> ${base}/${version}/data-formats/decimal128/ From c6f8a337c2c3f8e03c0e948de2a1c995b6384d42 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 10:54:19 -0400 Subject: [PATCH 35/48] test delete --- source/upgrade.txt | 127 --------------------------------------------- 1 file changed, 127 deletions(-) delete mode 100644 source/upgrade.txt diff --git a/source/upgrade.txt b/source/upgrade.txt deleted file mode 100644 index c37fc106..00000000 --- a/source/upgrade.txt +++ /dev/null @@ -1,127 +0,0 @@ -.. _php-upgrade: - -======================== -Upgrade Library Versions -======================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: compatibility, backwards compatibility - :description: Learn how to upgrade the MongoDB PHP Library and PHP extension, ensuring compatibility and addressing breaking changes. - -Overview --------- - -In this guide, you can learn about the changes you must make to your application -when you upgrade to a new version of the {+php-library+}. This page also describes -how to upgrade your {+extension-short+} to a new version. - -How to Upgrade --------------- - -Before you upgrade, perform the following actions: - -- Ensure the new {+library-short+} version is compatible with the {+mdb-server+} versions - your application connects to and the PHP version your - application compiles with. For version compatibility information, see the - :ref:`{+php-library+} Compatibility ` - page. -- Address any breaking changes between the library version - your application is using and your planned upgrade version in the - :ref:`Breaking Changes ` section. - -.. tip:: - - To ensure compatibility across {+mdb-server+} versions when - upgrading library versions, use the :ref:`{+stable-api+} `. - -Major and minor versions of the PHP extension and library are in sync. This -means you can run an upgrade command for the extension to also upgrade the PHP -library. - -Patch versions (x.x.x) for the library and extension are not in sync. Run the -respective commands to update to the patch versions for the library or extension. - -To upgrade the PHP extension, replace ```` with the version number -you want to upgrade to and run the following command in your application's -directory: - -.. code-block:: bash - - pecl upgrade mongodb- - -To upgrade the PHP library version, replace ```` with the -version number you want to upgrade to and run the following command in your -application's directory: - -.. code-block:: bash - - composer require mongodb/mongodb: - -Detailed installation instructions may be found in the -:php:`PHP.net documentation `. - -.. _php-breaking-changes: - -Breaking Changes ----------------- - -A breaking change is a change of a convention or a behavior starting in -a specific version of the library. This type of change may prevent your -application from working properly if not addressed before upgrading the -library. - -The breaking changes in this section are categorized by the library -version that introduced them. When upgrading library versions, address -all the breaking changes between the current and upgrade versions. - -For more information on release changes, see the release notes and -associated JIRA tickets for each release on `GitHub -`__. - -.. _php-v2-breaking-changes: - -Version 2.0 Breaking Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This library version introduces the following breaking changes: - -- The following methods return ``void`` instead of the raw command - response: - - - ``MongoDB\\Client``: ``dropDatabase()`` - - ``MongoDB\\Collection``: ``drop()``, ``dropIndex()``, - ``dropIndexes()``, ``dropSearchIndex()``, ``rename()`` - - ``MongoDB\\Database``: ``createCollection()``, ``drop()``, - ``dropCollection()``, ``renameCollection()`` - - The ``MongoDB\\Database::createEncryptedCollection()`` method returns - the list of encrypted fields instead of the raw command response. - - If there is an error, the methods throw an exception. - - If you must access the raw command response from the preceding - methods, you can register a :php:`CommandSubscriber - ` in your application. - -Version 1.20 Breaking Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This library version introduces the following breaking changes: - -- Drops support for {+mdb-server+} 3.6. - -Version 1.19 and Earlier -~~~~~~~~~~~~~~~~~~~~~~~~ - -For library versions 1.19 and earlier, see the release notes and associated -JIRA tickets for each release on `GitHub `__. From 488f61e7c3b9dbd82911e0f8707cd85bf7ea2df2 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 11:14:18 -0400 Subject: [PATCH 36/48] test --- source/{data-formats-temp.txt => data-formats.txt} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/{data-formats-temp.txt => data-formats.txt} (100%) diff --git a/source/data-formats-temp.txt b/source/data-formats.txt similarity index 100% rename from source/data-formats-temp.txt rename to source/data-formats.txt From a68cb2038f5442c5acfdce937f17a694d96dd105 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 11:29:08 -0400 Subject: [PATCH 37/48] test --- source/{indexes.txt => indexes-temp.txt} | 0 source/{reference-temp.txt => reference.txt} | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename source/{indexes.txt => indexes-temp.txt} (100%) rename source/{reference-temp.txt => reference.txt} (100%) diff --git a/source/indexes.txt b/source/indexes-temp.txt similarity index 100% rename from source/indexes.txt rename to source/indexes-temp.txt diff --git a/source/reference-temp.txt b/source/reference.txt similarity index 100% rename from source/reference-temp.txt rename to source/reference.txt From e7d990ff558172dc50c6d4b30fc2917bad39b93d Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 11:33:45 -0400 Subject: [PATCH 38/48] test --- source/{indexes-temp.txt => indexes.txt} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/{indexes-temp.txt => indexes.txt} (100%) diff --git a/source/indexes-temp.txt b/source/indexes.txt similarity index 100% rename from source/indexes-temp.txt rename to source/indexes.txt From d052cfd282536ffd29bb636e627c3336c09b9028 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 11:53:58 -0400 Subject: [PATCH 39/48] edits --- source/{faq-temp.txt => faq.txt} | 0 .../{monitoring => read}/change-streams.txt | 0 source/tutorial/commands.txt | 3 +- source/tutorial/server-selection.txt | 196 ++++++++++++++++++ 4 files changed, 198 insertions(+), 1 deletion(-) rename source/{faq-temp.txt => faq.txt} (100%) rename source/{monitoring => read}/change-streams.txt (100%) create mode 100644 source/tutorial/server-selection.txt diff --git a/source/faq-temp.txt b/source/faq.txt similarity index 100% rename from source/faq-temp.txt rename to source/faq.txt diff --git a/source/monitoring/change-streams.txt b/source/read/change-streams.txt similarity index 100% rename from source/monitoring/change-streams.txt rename to source/read/change-streams.txt diff --git a/source/tutorial/commands.txt b/source/tutorial/commands.txt index b36460b6..5351dfe0 100644 --- a/source/tutorial/commands.txt +++ b/source/tutorial/commands.txt @@ -151,4 +151,5 @@ The output would then resemble: ["ok"]=> float(1) } - } \ No newline at end of file + } +} \ No newline at end of file diff --git a/source/tutorial/server-selection.txt b/source/tutorial/server-selection.txt new file mode 100644 index 00000000..565bea29 --- /dev/null +++ b/source/tutorial/server-selection.txt @@ -0,0 +1,196 @@ +:orphan: + +=============================== +Server Selection and Monitoring +=============================== + +.. meta:: + :description: Understand how the MongoDB PHP Library selects and monitors servers, including connection string options for server selection and monitoring. + + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Server Selection and Monitoring +------------------------------- + +Before any operation can be executed, the |php-library| must first select a +server from the topology (e.g. replica set, sharded cluster). Selecting a server +requires an accurate view of the topology, so the extension regularly monitors +the servers to which it is connected. + +In most other drivers, server discovery and monitoring is handled by a +background thread; however, the PHP driver is single-threaded and must therefore +perform monitoring *between* operations initiated by the application. + +Consider the following example application: + +.. code-block:: php + + test; + + /** + * The library creates an internal object for this operation and must select + * a server to use for executing that operation. + * + * If this is the first operation on the underlying libmongoc client, it must + * first discover the topology. It does so by establishing connections to any + * host(s) in the seed list (this may entail TLS and OCSP verification) and + * issuing "hello" commands. + * + * In the case of a replica set, connecting to a single host in the seed list + * should allow the driver to discover all other members in the replica set. + * In the case of a sharded cluster, the driver will start with an initial + * seed list of mongos hosts and, if SRV polling is utilized, may discover + * additional mongos hosts over time. + * + * If the topology was already initialized (i.e. this is not the first + * operation on the client), the driver may still need to perform monitoring + * (i.e. "hello" commands) and refresh its view of the topology. This process + * may entail adding or removing hosts from the topology. + * + * Once the topology has been discovered and any necessary monitoring has + * been performed, the driver may select a server according to the rules + * outlined in the server selection specification (e.g. applying a read + * preference, filtering hosts by latency). + */ + $database->command(['ping' => 1]); + +Although the application consists of only a few lines of PHP, there is actually +quite a lot going on behind the scenes! Interested readers can find this process +discussed in greater detail in the following documents: + +- `Single-threaded Mode `_ in the libmongoc documentation +- `Server Discovery and Monitoring `_ specification +- `Server Selection `_ specification + +Connection String Options +------------------------- + +There are several connection string options relevant to server selection and +monitoring. + +connectTimeoutMS +~~~~~~~~~~~~~~~~ + +``connectTimeoutMS`` specifies the limit for both establishing a connection to +a server *and* the socket timeout for server monitoring (``hello`` commands). +This defaults to 10 seconds for single-threaded drivers such as PHP. + +When a server times out during monitoring, it will not be re-checked until at +least five seconds +(`cooldownMS `_) +have elapsed. This timeout is intended to avoid having single-threaded drivers +block for ``connectTimeoutMS`` on *each* subsequent scan after an error. + +Applications can consider setting this option to slightly more than the greatest +latency among servers in the cluster. For example, if the greatest ``ping`` time +between the PHP application server and a database server is 200ms, it may be +reasonable to specify a timeout of one second. This would allow ample time for +establishing a connection and monitoring an accessible server, while also +significantly reducing the time to detect an inaccessible server. + +heartbeatFrequencyMS +~~~~~~~~~~~~~~~~~~~~ + +``heartbeatFrequencyMS`` determines how often monitoring should occur. This +defaults to 60 seconds for single-threaded drivers and can be set as low as +500ms. + +serverSelectionTimeoutMS +~~~~~~~~~~~~~~~~~~~~~~~~ + +``serverSelectionTimeoutMS`` determines the maximum amount of time to spend in +the server selection loop. This defaults to 30 seconds, but applications will +typically fail sooner if ``serverSelectionTryOnce`` is ``true`` and a smaller +``connectTimeoutMS`` value is in effect. + +The original default was established at a time when replica set elections took +much longer to complete. Applications can consider setting this option to +slightly more than the expected completion time for an election. For example, +:manual:`Replica Set Elections ` states that +elections will not typically exceed 12 seconds, so a 15-second timeout may be +reasonable. Applications connecting to a sharded cluster may consider a smaller +value still, since ``mongos`` insulates the driver from elections. + +That said, ``serverSelectionTimeoutMS`` should generally not be set to a value +smaller than ``connectTimeoutMS``. + +serverSelectionTryOnce +~~~~~~~~~~~~~~~~~~~~~~ + +``serverSelectionTryOnce`` determines whether the driver should give up after +the first failed server selection attempt or continue waiting until +``serverSelectionTimeoutMS`` is reached. PHP defaults to ``true``, which allows +the driver to "fail fast" when a server cannot be selected (e.g. no primary +during a failover). + +The default behavior is generally desirable for a high-traffic web applications, +as it means the worker process will not be blocked in a server selection loop +and can instead return an error response and immediately go on to serve another +request. Additionally, other driver features such as retryable reads and writes +can still enable applications to avoid transient errors such as a failover. + +That said, applications that prioritize resiliency over response time (and +worker pool utilization) may want to specify ``false`` for +``serverSelectionTryOnce``. + +socketCheckIntervalMS +~~~~~~~~~~~~~~~~~~~~~ + +``socketCheckIntervalMS`` determines how often a socket should be checked (using +a ``ping`` command) if it has not been used recently. This defaults to 5 seconds +and is intentionally lower than ``heartbeatFrequencyMS`` to better allow +single-threaded drivers to recover dropped connections. + +socketTimeoutMS +~~~~~~~~~~~~~~~ + +``socketTimeoutMS`` determines the maximum amount of time to spend reading or +writing to a socket. Since server monitoring uses ``connectTimeoutMS`` for its +socket timeouts, ``socketTimeoutMS`` only applies to operations executed by the +application. + +``socketTimeoutMS`` defaults to 5 minutes; however, it's likely that a PHP web +request would be terminated sooner due to +`max_execution_time `_, +which defaults to 30 seconds for web SAPIs. In a CLI environment, where +``max_execution_time`` is unlimited by default, it is more likely that +``socketTimeoutMS`` could be reached. + +.. note:: + + ``socketTimeoutMS`` is not directly related to server selection and + monitoring; however, it is frequently associated with the other options and + therefore bears mentioning. \ No newline at end of file From 89e68e5771dbe3302c002a29f154f567a9433a55 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 11:55:58 -0400 Subject: [PATCH 40/48] test no changes --- source/upgrade.txt | 127 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 source/upgrade.txt diff --git a/source/upgrade.txt b/source/upgrade.txt new file mode 100644 index 00000000..6f1df22f --- /dev/null +++ b/source/upgrade.txt @@ -0,0 +1,127 @@ +.. _php-upgrade: + +======================== +Upgrade Library Versions +======================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: compatibility, backwards compatibility + :description: Learn how to upgrade the MongoDB PHP Library and PHP extension, ensuring compatibility and addressing breaking changes. + +Overview +-------- + +In this guide, you can learn about the changes you must make to your application +when you upgrade to a new version of the {+php-library+}. This page also describes +how to upgrade your {+extension-short+} to a new version. + +How to Upgrade +-------------- + +Before you upgrade, perform the following actions: + +- Ensure the new {+library-short+} version is compatible with the {+mdb-server+} versions + your application connects to and the PHP version your + application compiles with. For version compatibility information, see the + :ref:`{+php-library+} Compatibility ` + page. +- Address any breaking changes between the library version + your application is using and your planned upgrade version in the + :ref:`Breaking Changes ` section. + +.. tip:: + + To ensure compatibility across {+mdb-server+} versions when + upgrading library versions, use the :ref:`{+stable-api+} `. + +Major and minor versions of the PHP extension and library are in sync. This +means you can run an upgrade command for the extension to also upgrade the PHP +library. + +Patch versions (x.x.x) for the library and extension are not in sync. Run the +respective commands to update to the patch versions for the library or extension. + +To upgrade the PHP extension, replace ```` with the version number +you want to upgrade to and run the following command in your application's +directory: + +.. code-block:: bash + + pecl upgrade mongodb- + +To upgrade the PHP library version, replace ```` with the +version number you want to upgrade to and run the following command in your +application's directory: + +.. code-block:: bash + + composer require mongodb/mongodb: + +Detailed installation instructions may be found in the +:php:`PHP.net documentation `. + +.. _php-breaking-changes: + +Breaking Changes +---------------- + +A breaking change is a change of a convention or a behavior starting in +a specific version of the library. This type of change may prevent your +application from working properly if not addressed before upgrading the +library. + +The breaking changes in this section are categorized by the library +version that introduced them. When upgrading library versions, address +all the breaking changes between the current and upgrade versions. + +For more information on release changes, see the release notes and +associated JIRA tickets for each release on `GitHub +`__. + +.. _php-v2-breaking-changes: + +Version 2.0 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This library version introduces the following breaking changes: + +- The following methods return ``void`` instead of the raw command + response: + + - ``MongoDB\\Client``: ``dropDatabase()`` + - ``MongoDB\\Collection``: ``drop()``, ``dropIndex()``, + ``dropIndexes()``, ``dropSearchIndex()``, ``rename()`` + - ``MongoDB\\Database``: ``createCollection()``, ``drop()``, + ``dropCollection()``, ``renameCollection()`` + + The ``MongoDB\\Database::createEncryptedCollection()`` method returns + the list of encrypted fields instead of the raw command response. + + If there is an error, the methods throw an exception. + + If you must access the raw command response from the preceding + methods, you can register a :php:`CommandSubscriber + ` in your application. + +Version 1.20 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This library version introduces the following breaking changes: + +- Drops support for {+mdb-server+} 3.6. + +Version 1.19 and Earlier +~~~~~~~~~~~~~~~~~~~~~~~~ + +For library versions 1.19 and earlier, see the release notes and associated +JIRA tickets for each release on `GitHub `__. \ No newline at end of file From 13c7dd9d56eabb2bb481c014c680093b07fd9c8a Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 12:10:51 -0400 Subject: [PATCH 41/48] test bunch of changes --- source/{indexes.txt => indexes-temp.txt} | 0 .../{read => monitoring}/change-streams.txt | 0 source/tutorial/server-selection.txt | 196 ------------------ 3 files changed, 196 deletions(-) rename source/{indexes.txt => indexes-temp.txt} (100%) rename source/{read => monitoring}/change-streams.txt (100%) delete mode 100644 source/tutorial/server-selection.txt diff --git a/source/indexes.txt b/source/indexes-temp.txt similarity index 100% rename from source/indexes.txt rename to source/indexes-temp.txt diff --git a/source/read/change-streams.txt b/source/monitoring/change-streams.txt similarity index 100% rename from source/read/change-streams.txt rename to source/monitoring/change-streams.txt diff --git a/source/tutorial/server-selection.txt b/source/tutorial/server-selection.txt deleted file mode 100644 index 565bea29..00000000 --- a/source/tutorial/server-selection.txt +++ /dev/null @@ -1,196 +0,0 @@ -:orphan: - -=============================== -Server Selection and Monitoring -=============================== - -.. meta:: - :description: Understand how the MongoDB PHP Library selects and monitors servers, including connection string options for server selection and monitoring. - - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Server Selection and Monitoring -------------------------------- - -Before any operation can be executed, the |php-library| must first select a -server from the topology (e.g. replica set, sharded cluster). Selecting a server -requires an accurate view of the topology, so the extension regularly monitors -the servers to which it is connected. - -In most other drivers, server discovery and monitoring is handled by a -background thread; however, the PHP driver is single-threaded and must therefore -perform monitoring *between* operations initiated by the application. - -Consider the following example application: - -.. code-block:: php - - test; - - /** - * The library creates an internal object for this operation and must select - * a server to use for executing that operation. - * - * If this is the first operation on the underlying libmongoc client, it must - * first discover the topology. It does so by establishing connections to any - * host(s) in the seed list (this may entail TLS and OCSP verification) and - * issuing "hello" commands. - * - * In the case of a replica set, connecting to a single host in the seed list - * should allow the driver to discover all other members in the replica set. - * In the case of a sharded cluster, the driver will start with an initial - * seed list of mongos hosts and, if SRV polling is utilized, may discover - * additional mongos hosts over time. - * - * If the topology was already initialized (i.e. this is not the first - * operation on the client), the driver may still need to perform monitoring - * (i.e. "hello" commands) and refresh its view of the topology. This process - * may entail adding or removing hosts from the topology. - * - * Once the topology has been discovered and any necessary monitoring has - * been performed, the driver may select a server according to the rules - * outlined in the server selection specification (e.g. applying a read - * preference, filtering hosts by latency). - */ - $database->command(['ping' => 1]); - -Although the application consists of only a few lines of PHP, there is actually -quite a lot going on behind the scenes! Interested readers can find this process -discussed in greater detail in the following documents: - -- `Single-threaded Mode `_ in the libmongoc documentation -- `Server Discovery and Monitoring `_ specification -- `Server Selection `_ specification - -Connection String Options -------------------------- - -There are several connection string options relevant to server selection and -monitoring. - -connectTimeoutMS -~~~~~~~~~~~~~~~~ - -``connectTimeoutMS`` specifies the limit for both establishing a connection to -a server *and* the socket timeout for server monitoring (``hello`` commands). -This defaults to 10 seconds for single-threaded drivers such as PHP. - -When a server times out during monitoring, it will not be re-checked until at -least five seconds -(`cooldownMS `_) -have elapsed. This timeout is intended to avoid having single-threaded drivers -block for ``connectTimeoutMS`` on *each* subsequent scan after an error. - -Applications can consider setting this option to slightly more than the greatest -latency among servers in the cluster. For example, if the greatest ``ping`` time -between the PHP application server and a database server is 200ms, it may be -reasonable to specify a timeout of one second. This would allow ample time for -establishing a connection and monitoring an accessible server, while also -significantly reducing the time to detect an inaccessible server. - -heartbeatFrequencyMS -~~~~~~~~~~~~~~~~~~~~ - -``heartbeatFrequencyMS`` determines how often monitoring should occur. This -defaults to 60 seconds for single-threaded drivers and can be set as low as -500ms. - -serverSelectionTimeoutMS -~~~~~~~~~~~~~~~~~~~~~~~~ - -``serverSelectionTimeoutMS`` determines the maximum amount of time to spend in -the server selection loop. This defaults to 30 seconds, but applications will -typically fail sooner if ``serverSelectionTryOnce`` is ``true`` and a smaller -``connectTimeoutMS`` value is in effect. - -The original default was established at a time when replica set elections took -much longer to complete. Applications can consider setting this option to -slightly more than the expected completion time for an election. For example, -:manual:`Replica Set Elections ` states that -elections will not typically exceed 12 seconds, so a 15-second timeout may be -reasonable. Applications connecting to a sharded cluster may consider a smaller -value still, since ``mongos`` insulates the driver from elections. - -That said, ``serverSelectionTimeoutMS`` should generally not be set to a value -smaller than ``connectTimeoutMS``. - -serverSelectionTryOnce -~~~~~~~~~~~~~~~~~~~~~~ - -``serverSelectionTryOnce`` determines whether the driver should give up after -the first failed server selection attempt or continue waiting until -``serverSelectionTimeoutMS`` is reached. PHP defaults to ``true``, which allows -the driver to "fail fast" when a server cannot be selected (e.g. no primary -during a failover). - -The default behavior is generally desirable for a high-traffic web applications, -as it means the worker process will not be blocked in a server selection loop -and can instead return an error response and immediately go on to serve another -request. Additionally, other driver features such as retryable reads and writes -can still enable applications to avoid transient errors such as a failover. - -That said, applications that prioritize resiliency over response time (and -worker pool utilization) may want to specify ``false`` for -``serverSelectionTryOnce``. - -socketCheckIntervalMS -~~~~~~~~~~~~~~~~~~~~~ - -``socketCheckIntervalMS`` determines how often a socket should be checked (using -a ``ping`` command) if it has not been used recently. This defaults to 5 seconds -and is intentionally lower than ``heartbeatFrequencyMS`` to better allow -single-threaded drivers to recover dropped connections. - -socketTimeoutMS -~~~~~~~~~~~~~~~ - -``socketTimeoutMS`` determines the maximum amount of time to spend reading or -writing to a socket. Since server monitoring uses ``connectTimeoutMS`` for its -socket timeouts, ``socketTimeoutMS`` only applies to operations executed by the -application. - -``socketTimeoutMS`` defaults to 5 minutes; however, it's likely that a PHP web -request would be terminated sooner due to -`max_execution_time `_, -which defaults to 30 seconds for web SAPIs. In a CLI environment, where -``max_execution_time`` is unlimited by default, it is more likely that -``socketTimeoutMS`` could be reached. - -.. note:: - - ``socketTimeoutMS`` is not directly related to server selection and - monitoring; however, it is frequently associated with the other options and - therefore bears mentioning. \ No newline at end of file From 7b1bf8c7e670d3c06db25bfe131f4fff7f71c684 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 12:25:42 -0400 Subject: [PATCH 42/48] revert --- source/{indexes-temp.txt => indexes.txt} | 0 .../{monitoring => read}/change-streams.txt | 0 source/tutorial/server-selection.txt | 196 ++++++++++++++++++ 3 files changed, 196 insertions(+) rename source/{indexes-temp.txt => indexes.txt} (100%) rename source/{monitoring => read}/change-streams.txt (100%) create mode 100644 source/tutorial/server-selection.txt diff --git a/source/indexes-temp.txt b/source/indexes.txt similarity index 100% rename from source/indexes-temp.txt rename to source/indexes.txt diff --git a/source/monitoring/change-streams.txt b/source/read/change-streams.txt similarity index 100% rename from source/monitoring/change-streams.txt rename to source/read/change-streams.txt diff --git a/source/tutorial/server-selection.txt b/source/tutorial/server-selection.txt new file mode 100644 index 00000000..565bea29 --- /dev/null +++ b/source/tutorial/server-selection.txt @@ -0,0 +1,196 @@ +:orphan: + +=============================== +Server Selection and Monitoring +=============================== + +.. meta:: + :description: Understand how the MongoDB PHP Library selects and monitors servers, including connection string options for server selection and monitoring. + + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Server Selection and Monitoring +------------------------------- + +Before any operation can be executed, the |php-library| must first select a +server from the topology (e.g. replica set, sharded cluster). Selecting a server +requires an accurate view of the topology, so the extension regularly monitors +the servers to which it is connected. + +In most other drivers, server discovery and monitoring is handled by a +background thread; however, the PHP driver is single-threaded and must therefore +perform monitoring *between* operations initiated by the application. + +Consider the following example application: + +.. code-block:: php + + test; + + /** + * The library creates an internal object for this operation and must select + * a server to use for executing that operation. + * + * If this is the first operation on the underlying libmongoc client, it must + * first discover the topology. It does so by establishing connections to any + * host(s) in the seed list (this may entail TLS and OCSP verification) and + * issuing "hello" commands. + * + * In the case of a replica set, connecting to a single host in the seed list + * should allow the driver to discover all other members in the replica set. + * In the case of a sharded cluster, the driver will start with an initial + * seed list of mongos hosts and, if SRV polling is utilized, may discover + * additional mongos hosts over time. + * + * If the topology was already initialized (i.e. this is not the first + * operation on the client), the driver may still need to perform monitoring + * (i.e. "hello" commands) and refresh its view of the topology. This process + * may entail adding or removing hosts from the topology. + * + * Once the topology has been discovered and any necessary monitoring has + * been performed, the driver may select a server according to the rules + * outlined in the server selection specification (e.g. applying a read + * preference, filtering hosts by latency). + */ + $database->command(['ping' => 1]); + +Although the application consists of only a few lines of PHP, there is actually +quite a lot going on behind the scenes! Interested readers can find this process +discussed in greater detail in the following documents: + +- `Single-threaded Mode `_ in the libmongoc documentation +- `Server Discovery and Monitoring `_ specification +- `Server Selection `_ specification + +Connection String Options +------------------------- + +There are several connection string options relevant to server selection and +monitoring. + +connectTimeoutMS +~~~~~~~~~~~~~~~~ + +``connectTimeoutMS`` specifies the limit for both establishing a connection to +a server *and* the socket timeout for server monitoring (``hello`` commands). +This defaults to 10 seconds for single-threaded drivers such as PHP. + +When a server times out during monitoring, it will not be re-checked until at +least five seconds +(`cooldownMS `_) +have elapsed. This timeout is intended to avoid having single-threaded drivers +block for ``connectTimeoutMS`` on *each* subsequent scan after an error. + +Applications can consider setting this option to slightly more than the greatest +latency among servers in the cluster. For example, if the greatest ``ping`` time +between the PHP application server and a database server is 200ms, it may be +reasonable to specify a timeout of one second. This would allow ample time for +establishing a connection and monitoring an accessible server, while also +significantly reducing the time to detect an inaccessible server. + +heartbeatFrequencyMS +~~~~~~~~~~~~~~~~~~~~ + +``heartbeatFrequencyMS`` determines how often monitoring should occur. This +defaults to 60 seconds for single-threaded drivers and can be set as low as +500ms. + +serverSelectionTimeoutMS +~~~~~~~~~~~~~~~~~~~~~~~~ + +``serverSelectionTimeoutMS`` determines the maximum amount of time to spend in +the server selection loop. This defaults to 30 seconds, but applications will +typically fail sooner if ``serverSelectionTryOnce`` is ``true`` and a smaller +``connectTimeoutMS`` value is in effect. + +The original default was established at a time when replica set elections took +much longer to complete. Applications can consider setting this option to +slightly more than the expected completion time for an election. For example, +:manual:`Replica Set Elections ` states that +elections will not typically exceed 12 seconds, so a 15-second timeout may be +reasonable. Applications connecting to a sharded cluster may consider a smaller +value still, since ``mongos`` insulates the driver from elections. + +That said, ``serverSelectionTimeoutMS`` should generally not be set to a value +smaller than ``connectTimeoutMS``. + +serverSelectionTryOnce +~~~~~~~~~~~~~~~~~~~~~~ + +``serverSelectionTryOnce`` determines whether the driver should give up after +the first failed server selection attempt or continue waiting until +``serverSelectionTimeoutMS`` is reached. PHP defaults to ``true``, which allows +the driver to "fail fast" when a server cannot be selected (e.g. no primary +during a failover). + +The default behavior is generally desirable for a high-traffic web applications, +as it means the worker process will not be blocked in a server selection loop +and can instead return an error response and immediately go on to serve another +request. Additionally, other driver features such as retryable reads and writes +can still enable applications to avoid transient errors such as a failover. + +That said, applications that prioritize resiliency over response time (and +worker pool utilization) may want to specify ``false`` for +``serverSelectionTryOnce``. + +socketCheckIntervalMS +~~~~~~~~~~~~~~~~~~~~~ + +``socketCheckIntervalMS`` determines how often a socket should be checked (using +a ``ping`` command) if it has not been used recently. This defaults to 5 seconds +and is intentionally lower than ``heartbeatFrequencyMS`` to better allow +single-threaded drivers to recover dropped connections. + +socketTimeoutMS +~~~~~~~~~~~~~~~ + +``socketTimeoutMS`` determines the maximum amount of time to spend reading or +writing to a socket. Since server monitoring uses ``connectTimeoutMS`` for its +socket timeouts, ``socketTimeoutMS`` only applies to operations executed by the +application. + +``socketTimeoutMS`` defaults to 5 minutes; however, it's likely that a PHP web +request would be terminated sooner due to +`max_execution_time `_, +which defaults to 30 seconds for web SAPIs. In a CLI environment, where +``max_execution_time`` is unlimited by default, it is more likely that +``socketTimeoutMS`` could be reached. + +.. note:: + + ``socketTimeoutMS`` is not directly related to server selection and + monitoring; however, it is frequently associated with the other options and + therefore bears mentioning. \ No newline at end of file From 2aafebdb6bc180597c12c12a94a1b23035dda87f Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 14:25:32 -0400 Subject: [PATCH 43/48] add --- source/{indexes.txt => indexes-temp.txt} | 0 source/tutorial/server-selection.txt | 196 ----------------------- 2 files changed, 196 deletions(-) rename source/{indexes.txt => indexes-temp.txt} (100%) delete mode 100644 source/tutorial/server-selection.txt diff --git a/source/indexes.txt b/source/indexes-temp.txt similarity index 100% rename from source/indexes.txt rename to source/indexes-temp.txt diff --git a/source/tutorial/server-selection.txt b/source/tutorial/server-selection.txt deleted file mode 100644 index 565bea29..00000000 --- a/source/tutorial/server-selection.txt +++ /dev/null @@ -1,196 +0,0 @@ -:orphan: - -=============================== -Server Selection and Monitoring -=============================== - -.. meta:: - :description: Understand how the MongoDB PHP Library selects and monitors servers, including connection string options for server selection and monitoring. - - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Server Selection and Monitoring -------------------------------- - -Before any operation can be executed, the |php-library| must first select a -server from the topology (e.g. replica set, sharded cluster). Selecting a server -requires an accurate view of the topology, so the extension regularly monitors -the servers to which it is connected. - -In most other drivers, server discovery and monitoring is handled by a -background thread; however, the PHP driver is single-threaded and must therefore -perform monitoring *between* operations initiated by the application. - -Consider the following example application: - -.. code-block:: php - - test; - - /** - * The library creates an internal object for this operation and must select - * a server to use for executing that operation. - * - * If this is the first operation on the underlying libmongoc client, it must - * first discover the topology. It does so by establishing connections to any - * host(s) in the seed list (this may entail TLS and OCSP verification) and - * issuing "hello" commands. - * - * In the case of a replica set, connecting to a single host in the seed list - * should allow the driver to discover all other members in the replica set. - * In the case of a sharded cluster, the driver will start with an initial - * seed list of mongos hosts and, if SRV polling is utilized, may discover - * additional mongos hosts over time. - * - * If the topology was already initialized (i.e. this is not the first - * operation on the client), the driver may still need to perform monitoring - * (i.e. "hello" commands) and refresh its view of the topology. This process - * may entail adding or removing hosts from the topology. - * - * Once the topology has been discovered and any necessary monitoring has - * been performed, the driver may select a server according to the rules - * outlined in the server selection specification (e.g. applying a read - * preference, filtering hosts by latency). - */ - $database->command(['ping' => 1]); - -Although the application consists of only a few lines of PHP, there is actually -quite a lot going on behind the scenes! Interested readers can find this process -discussed in greater detail in the following documents: - -- `Single-threaded Mode `_ in the libmongoc documentation -- `Server Discovery and Monitoring `_ specification -- `Server Selection `_ specification - -Connection String Options -------------------------- - -There are several connection string options relevant to server selection and -monitoring. - -connectTimeoutMS -~~~~~~~~~~~~~~~~ - -``connectTimeoutMS`` specifies the limit for both establishing a connection to -a server *and* the socket timeout for server monitoring (``hello`` commands). -This defaults to 10 seconds for single-threaded drivers such as PHP. - -When a server times out during monitoring, it will not be re-checked until at -least five seconds -(`cooldownMS `_) -have elapsed. This timeout is intended to avoid having single-threaded drivers -block for ``connectTimeoutMS`` on *each* subsequent scan after an error. - -Applications can consider setting this option to slightly more than the greatest -latency among servers in the cluster. For example, if the greatest ``ping`` time -between the PHP application server and a database server is 200ms, it may be -reasonable to specify a timeout of one second. This would allow ample time for -establishing a connection and monitoring an accessible server, while also -significantly reducing the time to detect an inaccessible server. - -heartbeatFrequencyMS -~~~~~~~~~~~~~~~~~~~~ - -``heartbeatFrequencyMS`` determines how often monitoring should occur. This -defaults to 60 seconds for single-threaded drivers and can be set as low as -500ms. - -serverSelectionTimeoutMS -~~~~~~~~~~~~~~~~~~~~~~~~ - -``serverSelectionTimeoutMS`` determines the maximum amount of time to spend in -the server selection loop. This defaults to 30 seconds, but applications will -typically fail sooner if ``serverSelectionTryOnce`` is ``true`` and a smaller -``connectTimeoutMS`` value is in effect. - -The original default was established at a time when replica set elections took -much longer to complete. Applications can consider setting this option to -slightly more than the expected completion time for an election. For example, -:manual:`Replica Set Elections ` states that -elections will not typically exceed 12 seconds, so a 15-second timeout may be -reasonable. Applications connecting to a sharded cluster may consider a smaller -value still, since ``mongos`` insulates the driver from elections. - -That said, ``serverSelectionTimeoutMS`` should generally not be set to a value -smaller than ``connectTimeoutMS``. - -serverSelectionTryOnce -~~~~~~~~~~~~~~~~~~~~~~ - -``serverSelectionTryOnce`` determines whether the driver should give up after -the first failed server selection attempt or continue waiting until -``serverSelectionTimeoutMS`` is reached. PHP defaults to ``true``, which allows -the driver to "fail fast" when a server cannot be selected (e.g. no primary -during a failover). - -The default behavior is generally desirable for a high-traffic web applications, -as it means the worker process will not be blocked in a server selection loop -and can instead return an error response and immediately go on to serve another -request. Additionally, other driver features such as retryable reads and writes -can still enable applications to avoid transient errors such as a failover. - -That said, applications that prioritize resiliency over response time (and -worker pool utilization) may want to specify ``false`` for -``serverSelectionTryOnce``. - -socketCheckIntervalMS -~~~~~~~~~~~~~~~~~~~~~ - -``socketCheckIntervalMS`` determines how often a socket should be checked (using -a ``ping`` command) if it has not been used recently. This defaults to 5 seconds -and is intentionally lower than ``heartbeatFrequencyMS`` to better allow -single-threaded drivers to recover dropped connections. - -socketTimeoutMS -~~~~~~~~~~~~~~~ - -``socketTimeoutMS`` determines the maximum amount of time to spend reading or -writing to a socket. Since server monitoring uses ``connectTimeoutMS`` for its -socket timeouts, ``socketTimeoutMS`` only applies to operations executed by the -application. - -``socketTimeoutMS`` defaults to 5 minutes; however, it's likely that a PHP web -request would be terminated sooner due to -`max_execution_time `_, -which defaults to 30 seconds for web SAPIs. In a CLI environment, where -``max_execution_time`` is unlimited by default, it is more likely that -``socketTimeoutMS`` could be reached. - -.. note:: - - ``socketTimeoutMS`` is not directly related to server selection and - monitoring; however, it is frequently associated with the other options and - therefore bears mentioning. \ No newline at end of file From bbe06f295123fe479078b371fd950d5899657896 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 14:28:04 -0400 Subject: [PATCH 44/48] test --- source/{read => monitoring}/change-streams.txt | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/{read => monitoring}/change-streams.txt (100%) diff --git a/source/read/change-streams.txt b/source/monitoring/change-streams.txt similarity index 100% rename from source/read/change-streams.txt rename to source/monitoring/change-streams.txt From 37756ebea731a293bb5413b99a104ef377cf5591 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 14:31:50 -0400 Subject: [PATCH 45/48] test already added --- config/redirects | 3 +- source/{security.txt => security-temp.txt} | 0 source/tutorial/encryption.txt | 274 --------------------- 3 files changed, 2 insertions(+), 275 deletions(-) rename source/{security.txt => security-temp.txt} (100%) delete mode 100644 source/tutorial/encryption.txt diff --git a/config/redirects b/config/redirects index d437be97..f621802f 100644 --- a/config/redirects +++ b/config/redirects @@ -14,7 +14,8 @@ symlink: current -> v2.0 [*-v1.20]: ${prefix}/${version}/aggregation/vector-search -> ${base}/${version}/aggregation/ [*-v1.20]: ${prefix}/${version}/builders -> ${base}/${version}/ -# standardization redirects +[v1.20-*]: ${prefix}/${version}/security/ -> ${base}/${version}/security-temp/ +[v1.20-*]: ${prefix}/${version}/encryption/ -> ${base}/${version}/ # redirects in standardized docs [v1.20-*]: ${prefix}/${version}/tutorial/install-php-library/ -> ${base}/${version}/get-started/download-and-install/ diff --git a/source/security.txt b/source/security-temp.txt similarity index 100% rename from source/security.txt rename to source/security-temp.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 a0e071ffdb0867634424a810524d5b2bc8da9886 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 16 May 2025 14:33:46 -0400 Subject: [PATCH 46/48] test --- config/redirects | 1 - source/{security-temp.txt => security.txt} | 0 2 files changed, 1 deletion(-) rename source/{security-temp.txt => security.txt} (100%) diff --git a/config/redirects b/config/redirects index f621802f..bb748a68 100644 --- a/config/redirects +++ b/config/redirects @@ -14,7 +14,6 @@ symlink: current -> v2.0 [*-v1.20]: ${prefix}/${version}/aggregation/vector-search -> ${base}/${version}/aggregation/ [*-v1.20]: ${prefix}/${version}/builders -> ${base}/${version}/ -[v1.20-*]: ${prefix}/${version}/security/ -> ${base}/${version}/security-temp/ [v1.20-*]: ${prefix}/${version}/encryption/ -> ${base}/${version}/ # redirects in standardized docs diff --git a/source/security-temp.txt b/source/security.txt similarity index 100% rename from source/security-temp.txt rename to source/security.txt From 91da6b75207cddfd1ed752b2f285ba26afeb6b34 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 22 May 2025 10:19:10 -0400 Subject: [PATCH 47/48] add redirects --- config/redirects | 3 +++ 1 file changed, 3 insertions(+) diff --git a/config/redirects b/config/redirects index bb748a68..437af9fe 100644 --- a/config/redirects +++ b/config/redirects @@ -54,3 +54,6 @@ symlink: current -> v2.0 [*-v1.19]: ${prefix}/${version}/whats-new/ -> ${base}/${version}/ [*-v1.19]: ${prefix}/${version}/aws-lambda/ -> ${base}/${version}/tutorial/aws-lambda/ +[v1.20-*]: ${prefix}/${version}/indexes/ -> ${base}/${version}/indexes-temp/ +[v1.20-*]: ${prefix}/${version}/read/change-streams/ -> ${base}/${version}/monitoring/change-streams/ +[v1.20-*]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/${version}/ \ No newline at end of file From 29a87e5e498c1f6f18f47598153349585a6be707 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 22 May 2025 10:25:57 -0400 Subject: [PATCH 48/48] test --- config/redirects | 2 +- source/data-formats/codecs.txt | 118 --------------------------------- 2 files changed, 1 insertion(+), 119 deletions(-) delete mode 100644 source/data-formats/codecs.txt diff --git a/config/redirects b/config/redirects index 437af9fe..8d889d1a 100644 --- a/config/redirects +++ b/config/redirects @@ -56,4 +56,4 @@ symlink: current -> v2.0 [v1.20-*]: ${prefix}/${version}/indexes/ -> ${base}/${version}/indexes-temp/ [v1.20-*]: ${prefix}/${version}/read/change-streams/ -> ${base}/${version}/monitoring/change-streams/ -[v1.20-*]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/${version}/ \ No newline at end of file +[v1.20-*]: ${prefix}/${version}/tutorial/server-selection/ -> ${base}/${version}/connect/ \ No newline at end of file diff --git a/source/data-formats/codecs.txt b/source/data-formats/codecs.txt deleted file mode 100644 index b817eeb9..00000000 --- a/source/data-formats/codecs.txt +++ /dev/null @@ -1,118 +0,0 @@ -.. _php-codecs: - -====== -Codecs -====== - - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. versionadded:: 1.17 - -Overview --------- - -Codecs are used to decode BSON documents into PHP objects, and encode PHP objects into BSON documents. In contrast to -other methods (e.g. type maps), codecs allow for greater customization and handling of different data types. They -separate logic for BSON encoding and decoding from the domain classes, which also enables BSON to be decoded into plain -old PHP objects. - -Handling Documents ------------------- - -The main logic is contained in a document codec. This class implements the ``MongoDB\Codec\DocumentCodec`` interface and -defines what data types can be encoded/decoded and how. The following example defines a ``Person`` class and a codec to -transform it: - -.. literalinclude:: /examples/codecs/handling-documents/Person.php - :language: php - -.. literalinclude:: /examples/codecs/handling-documents/PersonCodec.php - :language: php - -To then use this codec with a collection, specify the ``codec`` option when selecting the collection: - -.. literalinclude:: /examples/codecs/handling-documents/using-codec.php - :language: php - -The example above selects a collection and instructs it to use the ``PersonCodec`` for encoding and decoding documents. -When inserting data, the ``PersonCodec`` is used to encode the document. When retrieving data, the same ``PersonCodec`` -is used to decode BSON data into a ``Person`` instance. Note that while the ``PersonCodec`` could technically decode any -BSON document that contains a name field, we wouldn't want to use it for any other documents. Document codecs are meant -to be used with a :phpclass:`MongoDB\Collection`, or when decoding embedded documents. - -When using a collection with a codec, the codec will only accept and return data of that type for certain operations. -Insert and replace operations (e.g. ``insertOne``, ```findOneAndReplace``, and some ``bulkWrite`` operations) will -attempt to encode the given data using the provided codec. Trying to insert or replace a document that cannot be encoded -will result in an exception. Read operations (e.g. ``aggregate``, ``find``, and ``findOneAndUpdate``) will attempt to -decode returned documents using the provided codec. If the codec does not support the data returned, an exception will -be thrown. - -You can disable codec usage for a specific operation or use a different codec (e.g. to decode the result of an -aggregation pipeline) by specifying ``null`` for the ``codec`` option for any operation. Alternatively, specifying a -type map using the ``typeMap`` operation will also override the collection-level codec: - -.. literalinclude:: /examples/codecs/handling-documents/disabling-codec.php - :language: php - -.. _php-codec-handling-data-types: - -Handling Fields and Data Types ------------------------------- - -The previous example showed how to define a codec for a specific class. However, you may want to create a codec that -handles a particular data type in any document. This can be achieved by implementing the ``MongoDB\Codec\Codec`` -interface. - -The following example defines a codec that stores ``DateTimeInterface`` instances as an embedded document containing a -BSON date and accompanying timezone string. Those same embedded documents can then be translated back into a -``DateTimeImmutable`` during BSON decoding. - -.. literalinclude:: /examples/codecs/handling-data-types/DateTimeCodec.php - :language: php - -.. note:: - When writing a codec, you should be as lenient as possible when it comes to handling data. In this case, the codec - handles any ``DateTimeInterface`` when encoding to BSON, as a ``UTCDateTime`` instance can be created from any such - object. When decoding data from BSON, it will always decode to a ``DateTimeImmutable`` instance. - -This codec can now be leveraged by other codecs that handle date fields. - -First, we add a ``createdAt`` field to the ``Person`` class: - -.. literalinclude:: /examples/codecs/handling-data-types/Person.php - :language: php - -Last but not least, we modify the codec to handle the new field: - -.. literalinclude:: /examples/codecs/handling-data-types/PersonCodec.php - :language: php - -Handling Embedded Documents ---------------------------- - -A previous example showed how to handle a single document. However, sometimes you want to handle fields that contain -embedded documents. We will demonstrate this using an ``Address`` document, which we will embed within a ``Person`` -document. To ensure consistency, we're going to make this a read-only class: - -.. literalinclude:: /examples/codecs/handling-embedded-documents/Address.php - :language: php - -We can now create a document codec for this class: - -.. literalinclude:: /examples/codecs/handling-embedded-documents/AddressCodec.php - :language: php - -The ``Person`` class gets a new ``address`` field, but we'll leave this optional: - -.. literalinclude:: /examples/codecs/handling-embedded-documents/Person.php - :language: php - -The ``PersonCodec`` can now handle the optional ``address`` field when transforming data: - -.. literalinclude:: /examples/codecs/handling-embedded-documents/PersonCodec.php - :language: php