From ff9f4a259a36dc027a856e1639ca97f6fc4514f4 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 1 Jul 2025 14:48:43 -0400 Subject: [PATCH 01/12] DOCSP-51123: CC edits and cleanup --- source/aggregation.txt | 7 ----- source/connect.txt | 30 +++++++++++++++++-- source/get-started.txt | 5 ++-- .../usage-examples/connect-code-examples.php | 16 ++++++++++ source/monitoring-logging/monitoring.txt | 6 ++-- 5 files changed, 49 insertions(+), 15 deletions(-) diff --git a/source/aggregation.txt b/source/aggregation.txt index a9b0d12a..44a7f142 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -389,13 +389,6 @@ learn more, see the :ref:`php-atlas-search` guide. You can perform similarity searches on vector embeddings by using the Atlas Vector Search feature. To learn more, see the :ref:`php-vector-search` guide. -.. TODO: - Aggregation Tutorials - ~~~~~~~~~~~~~~~~~~~~~ - -.. To view step-by-step explanations of common aggregation tasks, see -.. :ref:`php-aggregation-tutorials-landing`. - API Documentation ~~~~~~~~~~~~~~~~~ diff --git a/source/connect.txt b/source/connect.txt index 8ce1b09c..ccffe928 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -411,6 +411,30 @@ connection to your MongoDB instance: To learn more about the {+stable-api+}, see the :ref:`php-stable-api` guide. -.. TODO: - Network Compression - ------------------- \ No newline at end of file +Network Compression +------------------- + +The following code shows how to specify the Snappy, Zlib, and Zstandard +compression algorithms for a connection: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-compression-client + :end-before: end-compression-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/usage-examples/connect-code-examples.php + :language: php + :dedent: + :start-after: start-compression-uri + :end-before: end-compression-uri + +To learn more about network compression, see the :ref:`php-network-compression` guide. \ No newline at end of file diff --git a/source/get-started.txt b/source/get-started.txt index 6b2e1038..7e12eebb 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -191,9 +191,8 @@ The connection string includes the hostname or IP address and port of your deployment, the authentication mechanism, user credentials when applicable, and connection options. -.. TODO: - To connect to an instance or deployment not hosted on Atlas, see - :ref:`php-connection-targets`. +To connect to an instance or deployment not hosted on Atlas, see +:ref:`php-connection-targets`. .. procedure:: :style: connected diff --git a/source/includes/usage-examples/connect-code-examples.php b/source/includes/usage-examples/connect-code-examples.php index 631ad070..6d99847e 100644 --- a/source/includes/usage-examples/connect-code-examples.php +++ b/source/includes/usage-examples/connect-code-examples.php @@ -175,3 +175,19 @@ $driverOptions, ); // end-stable-api + +// Connects to a MongoDB deployment and compresses network traffic +// using client options +// start-compression-client +$client = new MongoDB\Client( + 'mongodb://:', + ['compressors' => 'snappy,zstd,zlib'], +); +// end-compression-client + +// Connects to a MongoDB deployment and compresses network traffic +// using connection URI parameters +// start-compression-uri +$uri = 'mongodb://:/?compressors=snappy,zstd,zlib'; +$client = new MongoDB\Client($uri); +// end-compression-uri \ No newline at end of file diff --git a/source/monitoring-logging/monitoring.txt b/source/monitoring-logging/monitoring.txt index 0a6af969..71600b98 100644 --- a/source/monitoring-logging/monitoring.txt +++ b/source/monitoring-logging/monitoring.txt @@ -32,9 +32,11 @@ events to track your application's performance and resource use. The {+php-library+} emits command events and Server Discovery and Monitoring (SDAM) events that provide application information. You can listen for these events to monitor your application. + +.. note:: -.. TODO: This page explains how to monitor your application in code. To learn how to - record this information to an external log, see the :ref:`php-logging` guide. + This page explains how to monitor your application in code. To learn how to + record this information to an external log, see the :ref:`php-logging` guide. Event Types ----------- From a39e9d2db2a29b7c4444ec87640e3d9cf55b117f Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 1 Jul 2025 14:56:22 -0400 Subject: [PATCH 02/12] build From 2006cb18e17002c007345e1d291d9477fe624650 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 1 Jul 2025 16:11:41 -0400 Subject: [PATCH 03/12] composer --- composer/composer.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/composer/composer.json b/composer/composer.json index 8892815e..8cbe58ad 100644 --- a/composer/composer.json +++ b/composer/composer.json @@ -2,8 +2,8 @@ "name": "mongodb/docs-php-library", "description": "MongoDB PHP Library Documentation", "require": { - "ext-mongodb": "^1.20", - "mongodb/mongodb": "^1.20" + "ext-mongodb": "^2.1", + "mongodb/mongodb": "^2.1" }, "require-dev": { "doctrine/coding-standard": "^12.0", @@ -15,4 +15,4 @@ "dealerdirect/phpcodesniffer-composer-installer": true } } -} +} \ No newline at end of file From 7a0fb0f5a5d8149b46530ee20ef51a636a010f25 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 1 Jul 2025 16:30:38 -0400 Subject: [PATCH 04/12] code errors --- source/includes/connect/client.php | 2 +- source/includes/monitoring-logging/logging.php | 7 ++----- source/includes/monitoring-logging/monitor.php | 4 +++- 3 files changed, 6 insertions(+), 7 deletions(-) diff --git a/source/includes/connect/client.php b/source/includes/connect/client.php index ee2d337b..7bde69d9 100644 --- a/source/includes/connect/client.php +++ b/source/includes/connect/client.php @@ -3,4 +3,4 @@ $uri = 'mongodb://localhost:27017'; $uriOptions = ['serverSelectionTimeoutMS' => 10000]; -$client = new MongoDB\Client($uri, $uriOptions); \ No newline at end of file +$client = new MongoDB\Client($uri, $uriOptions); diff --git a/source/includes/monitoring-logging/logging.php b/source/includes/monitoring-logging/logging.php index 8a97b794..c9d1a66d 100644 --- a/source/includes/monitoring-logging/logging.php +++ b/source/includes/monitoring-logging/logging.php @@ -3,8 +3,8 @@ require 'vendor/autoload.php'; // start-monolog-logger -use Monolog\Logger; use Monolog\Handler\StreamHandler; +use Monolog\Logger; $logger = new Logger('mongodb-logger'); $logger->pushHandler(new StreamHandler(__DIR__ . '/mongodb.log', Logger::DEBUG)); @@ -14,15 +14,12 @@ // start-custom-logger use Psr\Log\AbstractLogger; -use Psr\Log\LoggerInterface; -use Psr\Log\LogLevel; -use MongoDB\PsrLogAdapter; class MyLogger extends AbstractLogger { public array $logs = []; - public function log($level, $message, array $context = []): void + public function log(string $level, string|\Stringable $message, array $context = []): void { $this->logs[] = [$level, $message, $context['domain']]; } diff --git a/source/includes/monitoring-logging/monitor.php b/source/includes/monitoring-logging/monitor.php index 2d1123b7..9cc772c0 100644 --- a/source/includes/monitoring-logging/monitor.php +++ b/source/includes/monitoring-logging/monitor.php @@ -5,7 +5,9 @@ // start-command-subscriber class MyCommandSubscriber implements MongoDB\Driver\Monitoring\CommandSubscriber { - public function __construct(private $stream) {} + /** @param resource $stream */ + public function __construct(private $stream) + {} public function commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent $event): void { From 9aba3781f84c2349ac91509453be5e9551fef9b3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 1 Jul 2025 17:08:28 -0400 Subject: [PATCH 05/12] commas --- source/includes/bson.php | 4 ++-- source/includes/connect/ca-file-tabs.rst | 2 +- source/includes/connect/client-cert-tabs.rst | 2 +- source/includes/connect/crl-tabs.rst | 2 +- source/includes/connect/disable-cert-validation-tabs.rst | 2 +- source/includes/connect/disable-host-verification-tabs.rst | 2 +- source/includes/connect/insecure-tls-tabs.rst | 2 +- source/includes/connect/key-file-password.rst | 2 +- source/includes/connect/ocsp-tabs.rst | 2 +- source/includes/extended-json.php | 2 +- source/includes/monitoring-logging/monitor.php | 4 +++- source/includes/usage-examples/connect-code-examples.php | 2 +- 12 files changed, 15 insertions(+), 13 deletions(-) diff --git a/source/includes/bson.php b/source/includes/bson.php index cb2a510d..2a13ef73 100644 --- a/source/includes/bson.php +++ b/source/includes/bson.php @@ -28,8 +28,8 @@ 'typeMap' => [ 'array' => 'MongoDB\Model\BSONDocument', 'root' => 'MongoDB\Model\BSONDocument', - 'document' => 'MongoDB\Model\BSONDocument' - ] + 'document' => 'MongoDB\Model\BSONDocument', + ], ]; $db->createCollection('restaurants', $options); diff --git a/source/includes/connect/ca-file-tabs.rst b/source/includes/connect/ca-file-tabs.rst index 57bfd343..4cae5b03 100644 --- a/source/includes/connect/ca-file-tabs.rst +++ b/source/includes/connect/ca-file-tabs.rst @@ -9,7 +9,7 @@ $options = [ 'tls' => true, - 'tlsCAFile' => '/path/to/ca.pem' + 'tlsCAFile' => '/path/to/ca.pem' , ]; $client = new MongoDB\Client($uri, $options); diff --git a/source/includes/connect/client-cert-tabs.rst b/source/includes/connect/client-cert-tabs.rst index a93a9185..94d77221 100644 --- a/source/includes/connect/client-cert-tabs.rst +++ b/source/includes/connect/client-cert-tabs.rst @@ -9,7 +9,7 @@ $options = [ 'tls' => true, - 'tlsCertificateKeyFile' => '/path/to/client.pem' + 'tlsCertificateKeyFile' => '/path/to/client.pem', ]; $client = new MongoDB\Client($uri, $options); diff --git a/source/includes/connect/crl-tabs.rst b/source/includes/connect/crl-tabs.rst index 3784ce06..8caf0b03 100644 --- a/source/includes/connect/crl-tabs.rst +++ b/source/includes/connect/crl-tabs.rst @@ -9,7 +9,7 @@ $options = [ 'tls' => true, - 'tlsCRLFile' => '/path/to/crl.pem' + 'tlsCRLFile' => '/path/to/crl.pem', ]; $client = new MongoDB\Client($uri, $options); diff --git a/source/includes/connect/disable-cert-validation-tabs.rst b/source/includes/connect/disable-cert-validation-tabs.rst index 60e77093..9b1c47e7 100644 --- a/source/includes/connect/disable-cert-validation-tabs.rst +++ b/source/includes/connect/disable-cert-validation-tabs.rst @@ -9,7 +9,7 @@ $options = [ 'tls' => true, - 'tlsAllowInvalidCertificates' => true + 'tlsAllowInvalidCertificates' => true, ]; $client = new MongoDB\Client($uri, $options); diff --git a/source/includes/connect/disable-host-verification-tabs.rst b/source/includes/connect/disable-host-verification-tabs.rst index 96cc4cfc..33b2e8cd 100644 --- a/source/includes/connect/disable-host-verification-tabs.rst +++ b/source/includes/connect/disable-host-verification-tabs.rst @@ -9,7 +9,7 @@ $options = [ 'tls' => true, - 'tlsAllowInvalidHostnames' => true + 'tlsAllowInvalidHostnames' => true, ]; $client = new MongoDB\Client($uri, $options); diff --git a/source/includes/connect/insecure-tls-tabs.rst b/source/includes/connect/insecure-tls-tabs.rst index e04e56ea..ba1f3158 100644 --- a/source/includes/connect/insecure-tls-tabs.rst +++ b/source/includes/connect/insecure-tls-tabs.rst @@ -9,7 +9,7 @@ $options = [ 'tls' => true, - 'tlsInsecure' => true + 'tlsInsecure' => true, ]; $client = new MongoDB\Client($uri, $options); diff --git a/source/includes/connect/key-file-password.rst b/source/includes/connect/key-file-password.rst index a6b2f8ea..200f8189 100644 --- a/source/includes/connect/key-file-password.rst +++ b/source/includes/connect/key-file-password.rst @@ -10,7 +10,7 @@ $options = [ 'tls' => true, 'tlsCertificateKeyFile' => '/path/to/client.pem', - 'tlsCertificateKeyFilePassword' => '' + 'tlsCertificateKeyFilePassword' => '', ]; $client = new MongoDB\Client($uri, $options); diff --git a/source/includes/connect/ocsp-tabs.rst b/source/includes/connect/ocsp-tabs.rst index 467fed14..87978476 100644 --- a/source/includes/connect/ocsp-tabs.rst +++ b/source/includes/connect/ocsp-tabs.rst @@ -9,7 +9,7 @@ $options = [ 'tls' => true, - 'tlsDisableOCSPEndpointCheck' => true + 'tlsDisableOCSPEndpointCheck' => true, ]; $client = new MongoDB\Client($uri, $options); diff --git a/source/includes/extended-json.php b/source/includes/extended-json.php index f1ad0e9c..61f66a15 100644 --- a/source/includes/extended-json.php +++ b/source/includes/extended-json.php @@ -7,7 +7,7 @@ 'foo' => [1, 2], 'bar' => ['hello' => 'world'], 'code' => new MongoDB\BSON\Javascript('function x() { return 1; }', []), - 'date' => new DateTime('2024-07-20 10:30:00') + 'date' => new DateTime('2024-07-20 10:30:00'), ]; echo 'Relaxed format: ' , MongoDB\BSON\Document::fromPHP($doc)->toRelaxedExtendedJSON(), PHP_EOL; diff --git a/source/includes/monitoring-logging/monitor.php b/source/includes/monitoring-logging/monitor.php index 9cc772c0..c93ea853 100644 --- a/source/includes/monitoring-logging/monitor.php +++ b/source/includes/monitoring-logging/monitor.php @@ -7,7 +7,8 @@ class MyCommandSubscriber implements MongoDB\Driver\Monitoring\CommandSubscriber { /** @param resource $stream */ public function __construct(private $stream) - {} + { + } public function commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent $event): void { @@ -28,6 +29,7 @@ public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent $even // start-sdam-subscriber class MySDAMSubscriber implements MongoDB\Driver\Monitoring\SDAMSubscriber { + /** @param resource $stream */ public function __construct(private $stream) {} public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $event): void { diff --git a/source/includes/usage-examples/connect-code-examples.php b/source/includes/usage-examples/connect-code-examples.php index 6d99847e..82854aec 100644 --- a/source/includes/usage-examples/connect-code-examples.php +++ b/source/includes/usage-examples/connect-code-examples.php @@ -190,4 +190,4 @@ // start-compression-uri $uri = 'mongodb://:/?compressors=snappy,zstd,zlib'; $client = new MongoDB\Client($uri); -// end-compression-uri \ No newline at end of file +// end-compression-uri From 9c13c6fbb9611cc93f0ad5ffaff92d8724b7cdc1 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 1 Jul 2025 17:32:42 -0400 Subject: [PATCH 06/12] more phpcs errors --- source/data-formats/modeling-bson-data.txt | 31 ++++-- source/includes/bson.php | 117 --------------------- source/includes/bson/Person.php | 35 ++++++ source/includes/bson/Role.php | 11 ++ source/includes/bson/User.php | 30 ++++++ source/includes/bson/interact-bson.php | 56 ++++++++++ 6 files changed, 152 insertions(+), 128 deletions(-) delete mode 100644 source/includes/bson.php create mode 100644 source/includes/bson/Person.php create mode 100644 source/includes/bson/Role.php create mode 100644 source/includes/bson/User.php create mode 100644 source/includes/bson/interact-bson.php diff --git a/source/data-formats/modeling-bson-data.txt b/source/data-formats/modeling-bson-data.txt index 44257396..7389c3df 100644 --- a/source/data-formats/modeling-bson-data.txt +++ b/source/data-formats/modeling-bson-data.txt @@ -57,7 +57,7 @@ these values into BSON documents when inserting them into a collection. The following example creates a BSON document that represents the preceding :ref:`sample BSON document `: -.. literalinclude:: /includes/bson.php +.. literalinclude:: /includes/bson/interact-bson.php :language: php :dedent: :start-after: start-create-doc @@ -73,7 +73,7 @@ to the :ref:`sample BSON document `: - Adds a new ``restaurant_id`` field that has a value of ``12345`` - Changes the ``name`` field value to ``"Galaxy Pizza"`` -.. literalinclude:: /includes/bson.php +.. literalinclude:: /includes/bson/interact-bson.php :language: php :dedent: :start-after: start-modify-doc @@ -142,7 +142,7 @@ Custom Type Map Example The following example sets the ``typeMap`` option for the ``restaurants`` collection that serializes arrays and BSON documents as ``MongoDB\Model\BSONDocument`` objects: -.. literalinclude:: /includes/bson.php +.. literalinclude:: /includes/bson/interact-bson.php :language: php :dedent: :start-after: start-type-map @@ -170,7 +170,7 @@ Consider the following ``Person`` class definition, which implements the ``Persistable`` interface and specifies how to serialize and deserialize object fields as BSON values: -.. literalinclude:: /includes/bson.php +.. literalinclude:: /includes/bson/Person.php :language: php :dedent: :start-after: start-person-class @@ -182,7 +182,7 @@ database, and reads it back as an object of the same type: .. io-code-block:: :copyable: - .. input:: /includes/bson.php + .. input:: /includes/bson/interact-bson.php :start-after: start-person-serialize :end-before: end-person-serialize :language: php @@ -245,24 +245,33 @@ and ``bsonUnserialize()`` methods in your class definition. Example ``````` -Consider the following ``User`` class definition, which specifies -logic for serializing and deserializing its fields into BSON values. -The class includes a ``role`` field, which has a backed enum value: +Consider the following backed enum named ``Role``, which has two +integer-valued cases: -.. literalinclude:: /includes/bson.php +.. literalinclude:: /includes/bson/Role.php :language: php - :emphasize-lines: 15, 24 :dedent: :start-after: start-backed-enum :end-before: end-backed-enum +This ``User`` class definition includes a ``role`` field with a ``Role`` enum +value and specifies logic for serializing and deserializing its fields into BSON +values: + +.. literalinclude:: /includes/bson/User.php + :language: php + :emphasize-lines: 5 + :dedent: + :start-after: start-user-class + :end-before: end-user-class + The following example constructs a ``User`` object with a ``role`` field, inserts it into the database, and reads it back as an object of the same type: .. io-code-block:: :copyable: - .. input:: /includes/bson.php + .. input:: /includes/bson/interact-bson.php :start-after: start-enum-serialize :end-before: end-enum-serialize :language: php diff --git a/source/includes/bson.php b/source/includes/bson.php deleted file mode 100644 index 2a13ef73..00000000 --- a/source/includes/bson.php +++ /dev/null @@ -1,117 +0,0 @@ -test; - -// start-create-doc -$document = [ - 'address' => [ - 'street' => 'Pizza St', - 'zipcode' => '10003' - ], - 'coord' => [-73.982419, 41.579505], - 'cuisine' => 'Pizza', - 'name' => 'Planet Pizza' -]; -// end-create-doc - -// start-modify-doc -$document['restaurant_id'] = 12345; -$document['name'] = 'Galaxy Pizza'; -// end-modify-doc - -// start-type-map -$options = [ - 'typeMap' => [ - 'array' => 'MongoDB\Model\BSONDocument', - 'root' => 'MongoDB\Model\BSONDocument', - 'document' => 'MongoDB\Model\BSONDocument', - ], -]; - -$db->createCollection('restaurants', $options); -// end-type-map - -// start-person-class -class Person implements MongoDB\BSON\Persistable -{ - private MongoDB\BSON\ObjectId $id; - private string $name; - private MongoDB\BSON\UTCDateTime $createdAt; - - public function __construct(string $name) - { - $this->id = new MongoDB\BSON\ObjectId; - $this->name = $name; - $this->createdAt = new MongoDB\BSON\UTCDateTime; - } - - function bsonSerialize() - { - return [ - '_id' => $this->id, - 'name' => $this->name, - 'createdAt' => $this->createdAt, - ]; - } - - function bsonUnserialize(array $data) - { - $this->id = $data['_id']; - $this->name = $data['name']; - $this->createdAt = $data['createdAt']; - } -} -// end-person-class - -// start-person-serialize -$collection = $client->test->persons; -$result = $collection->insertOne(new Person('Bob')); -$person = $collection->findOne(['_id' => $result->getInsertedId()]); - -var_dump($person); -// end-person-serialize - -// start-backed-enum -enum Role: int -{ - case USER = 1; - case ADMIN = 2; -} - -class User implements MongoDB\BSON\Persistable -{ - public function __construct( - private string $username, - private Role $role, - private MongoDB\BSON\ObjectId $_id = new MongoDB\BSON\ObjectId(), - ) {} - - public function bsonSerialize(): array - { - return [ - '_id' => $this->_id, - 'username' => $this->username, - 'role' => $this->role, - ]; - } - - public function bsonUnserialize(array $data): void - { - $this->_id = $data['_id']; - $this->username = $data['username']; - $this->role = Role::from($data['role']); - } -} -// end-backed-enum - -// start-enum-serialize -$collection = $client->test->users; -$result = $collection->insertOne(new User('alice', Role::USER)); -$person = $collection->findOne(['_id' => $result->getInsertedId()]); - -var_dump($person); -// end-enum-serialize \ No newline at end of file diff --git a/source/includes/bson/Person.php b/source/includes/bson/Person.php new file mode 100644 index 00000000..9a069692 --- /dev/null +++ b/source/includes/bson/Person.php @@ -0,0 +1,35 @@ +id = new MongoDB\BSON\ObjectId; + $this->name = $name; + $this->createdAt = new MongoDB\BSON\UTCDateTime; + } + + function bsonSerialize() + { + return [ + '_id' => $this->id, + 'name' => $this->name, + 'createdAt' => $this->createdAt, + ]; + } + + function bsonUnserialize(array $data) + { + $this->id = $data['_id']; + $this->name = $data['name']; + $this->createdAt = $data['createdAt']; + } +} +// end-person-class diff --git a/source/includes/bson/Role.php b/source/includes/bson/Role.php new file mode 100644 index 00000000..c4239e74 --- /dev/null +++ b/source/includes/bson/Role.php @@ -0,0 +1,11 @@ + $this->_id, + 'username' => $this->username, + 'role' => $this->role, + ]; + } + + public function bsonUnserialize(array $data): void + { + $this->_id = $data['_id']; + $this->username = $data['username']; + $this->role = Role::from($data['role']); + } +} +// end-user-class diff --git a/source/includes/bson/interact-bson.php b/source/includes/bson/interact-bson.php new file mode 100644 index 00000000..693290be --- /dev/null +++ b/source/includes/bson/interact-bson.php @@ -0,0 +1,56 @@ +test; + +// start-create-doc +$document = [ + 'address' => [ + 'street' => 'Pizza St', + 'zipcode' => '10003' + ], + 'coord' => [-73.982419, 41.579505], + 'cuisine' => 'Pizza', + 'name' => 'Planet Pizza' +]; +// end-create-doc + +// start-modify-doc +$document['restaurant_id'] = 12345; +$document['name'] = 'Galaxy Pizza'; +// end-modify-doc + +// start-type-map +$options = [ + 'typeMap' => [ + 'array' => 'MongoDB\Model\BSONDocument', + 'root' => 'MongoDB\Model\BSONDocument', + 'document' => 'MongoDB\Model\BSONDocument', + ], +]; + +$db->createCollection('restaurants', $options); +// end-type-map + +// start-person-serialize +$collection = $client->test->persons; +$result = $collection->insertOne(new Person('Bob')); +$person = $collection->findOne(['_id' => $result->getInsertedId()]); + +var_dump($person); +// end-person-serialize + +// start-enum-serialize +$collection = $client->test->users; +$result = $collection->insertOne(new User('alice', Role::USER)); +$person = $collection->findOne(['_id' => $result->getInsertedId()]); + +var_dump($person); +// end-enum-serialize \ No newline at end of file From f79676c48d3ab9acba9271b4bad01697bc3b0bc3 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 1 Jul 2025 17:38:34 -0400 Subject: [PATCH 07/12] edits --- source/includes/bson/Person.php | 4 ++-- source/includes/bson/User.php | 3 ++- source/includes/bson/interact-bson.php | 10 +++++----- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/source/includes/bson/Person.php b/source/includes/bson/Person.php index 9a069692..9080f911 100644 --- a/source/includes/bson/Person.php +++ b/source/includes/bson/Person.php @@ -16,7 +16,7 @@ public function __construct(string $name) $this->createdAt = new MongoDB\BSON\UTCDateTime; } - function bsonSerialize() + public function bsonSerialize(): array { return [ '_id' => $this->id, @@ -25,7 +25,7 @@ function bsonSerialize() ]; } - function bsonUnserialize(array $data) + public function bsonUnserialize(array $data): void { $this->id = $data['_id']; $this->name = $data['name']; diff --git a/source/includes/bson/User.php b/source/includes/bson/User.php index f5f7c885..89b8ecf1 100644 --- a/source/includes/bson/User.php +++ b/source/includes/bson/User.php @@ -9,7 +9,8 @@ public function __construct( private string $username, private Role $role, private MongoDB\BSON\ObjectId $_id = new MongoDB\BSON\ObjectId(), - ) {} + ) { + } public function bsonSerialize(): array { diff --git a/source/includes/bson/interact-bson.php b/source/includes/bson/interact-bson.php index 693290be..70b41b2b 100644 --- a/source/includes/bson/interact-bson.php +++ b/source/includes/bson/interact-bson.php @@ -3,8 +3,8 @@ require 'vendor/autoload.php'; use Bson\Person; -use Bson\User; use Bson\Role; +use Bson\User; $uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your Atlas URI that connects to the sample dataset'); $client = new MongoDB\Client($uri); @@ -14,11 +14,11 @@ $document = [ 'address' => [ 'street' => 'Pizza St', - 'zipcode' => '10003' + 'zipcode' => '10003', ], 'coord' => [-73.982419, 41.579505], 'cuisine' => 'Pizza', - 'name' => 'Planet Pizza' + 'name' => 'Planet Pizza', ]; // end-create-doc @@ -31,7 +31,7 @@ $options = [ 'typeMap' => [ 'array' => 'MongoDB\Model\BSONDocument', - 'root' => 'MongoDB\Model\BSONDocument', + 'root' => 'MongoDB\Model\BSONDocument', 'document' => 'MongoDB\Model\BSONDocument', ], ]; @@ -53,4 +53,4 @@ $person = $collection->findOne(['_id' => $result->getInsertedId()]); var_dump($person); -// end-enum-serialize \ No newline at end of file +// end-enum-serialize From ead4cecf9859b3031a3e2cfbd5c799e5dd0dcc16 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 1 Jul 2025 17:55:16 -0400 Subject: [PATCH 08/12] phpcs --- source/includes/bson/Person.php | 13 +++++-------- source/includes/monitoring-logging/monitor.php | 13 ++++++++++--- 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/source/includes/bson/Person.php b/source/includes/bson/Person.php index 9080f911..b2dc3ed9 100644 --- a/source/includes/bson/Person.php +++ b/source/includes/bson/Person.php @@ -5,15 +5,12 @@ // start-person-class class Person implements MongoDB\BSON\Persistable { - private MongoDB\BSON\ObjectId $id; - private string $name; - private MongoDB\BSON\UTCDateTime $createdAt; + private \MongoDB\BSON\ObjectId $id; + private \MongoDB\BSON\UTCDateTime $createdAt; - public function __construct(string $name) - { - $this->id = new MongoDB\BSON\ObjectId; - $this->name = $name; - $this->createdAt = new MongoDB\BSON\UTCDateTime; + public function __construct(private string $name) { + $this->id = new \MongoDB\BSON\ObjectId(); + $this->createdAt = new \MongoDB\BSON\UTCDateTime(); } public function bsonSerialize(): array diff --git a/source/includes/monitoring-logging/monitor.php b/source/includes/monitoring-logging/monitor.php index c93ea853..9668483b 100644 --- a/source/includes/monitoring-logging/monitor.php +++ b/source/includes/monitoring-logging/monitor.php @@ -21,8 +21,13 @@ public function commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent $ev )); } - public function commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent $event): void {} - public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent $event): void {} + public function commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent $event): void + { + } + + public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent $event): void + { + } } // end-command-subscriber @@ -30,7 +35,9 @@ public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent $even class MySDAMSubscriber implements MongoDB\Driver\Monitoring\SDAMSubscriber { /** @param resource $stream */ - public function __construct(private $stream) {} + public function __construct(private $stream) + { + } public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $event): void { fprintf( From fb6ecc7cc6a42aef26fef56766c9f75e445624d6 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 1 Jul 2025 17:57:48 -0400 Subject: [PATCH 09/12] code fixes --- source/includes/bson/Person.php | 3 ++- source/includes/extended-json.php | 2 +- source/includes/monitoring-logging/monitor.php | 3 ++- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/source/includes/bson/Person.php b/source/includes/bson/Person.php index b2dc3ed9..cd63e419 100644 --- a/source/includes/bson/Person.php +++ b/source/includes/bson/Person.php @@ -8,7 +8,8 @@ class Person implements MongoDB\BSON\Persistable private \MongoDB\BSON\ObjectId $id; private \MongoDB\BSON\UTCDateTime $createdAt; - public function __construct(private string $name) { + public function __construct(private string $name) + { $this->id = new \MongoDB\BSON\ObjectId(); $this->createdAt = new \MongoDB\BSON\UTCDateTime(); } diff --git a/source/includes/extended-json.php b/source/includes/extended-json.php index 61f66a15..0c4398b7 100644 --- a/source/includes/extended-json.php +++ b/source/includes/extended-json.php @@ -30,4 +30,4 @@ $decodedJson = json_decode($ejsonStr, true); print_r($decodedJson); -// end-read-extended \ No newline at end of file +// end-read-extended diff --git a/source/includes/monitoring-logging/monitor.php b/source/includes/monitoring-logging/monitor.php index 9668483b..453c40da 100644 --- a/source/includes/monitoring-logging/monitor.php +++ b/source/includes/monitoring-logging/monitor.php @@ -39,7 +39,8 @@ public function __construct(private $stream) { } - public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $event): void { + public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $event): void + { fprintf( $this->stream, 'Server opening on %s:%s\n', From f170802ca51ea2cd886c2e14d9bc85da37ef5204 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 2 Jul 2025 10:20:28 -0400 Subject: [PATCH 10/12] more phpcs --- .../MyCommandSubscriber.php | 32 +++++++ .../monitoring-logging/MySdamSubscriber.php | 56 +++++++++++++ .../includes/monitoring-logging/logging.php | 4 +- .../includes/monitoring-logging/monitor.php | 83 +------------------ source/monitoring-logging/monitoring.txt | 4 +- 5 files changed, 93 insertions(+), 86 deletions(-) create mode 100644 source/includes/monitoring-logging/MyCommandSubscriber.php create mode 100644 source/includes/monitoring-logging/MySdamSubscriber.php diff --git a/source/includes/monitoring-logging/MyCommandSubscriber.php b/source/includes/monitoring-logging/MyCommandSubscriber.php new file mode 100644 index 00000000..5798aca3 --- /dev/null +++ b/source/includes/monitoring-logging/MyCommandSubscriber.php @@ -0,0 +1,32 @@ +stream, sprintf( + 'Started command #%d "%s": %s%s', + $event->getRequestId(), + $event->getCommandName(), + MongoDB\BSON\Document::fromPHP($event->getCommand())->toCanonicalExtendedJSON(), + PHP_EOL, + )); + } + + public function commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent $event): void + { + } + + public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent $event): void + { + } +} +// end-command-subscriber \ No newline at end of file diff --git a/source/includes/monitoring-logging/MySdamSubscriber.php b/source/includes/monitoring-logging/MySdamSubscriber.php new file mode 100644 index 00000000..4b9a77d7 --- /dev/null +++ b/source/includes/monitoring-logging/MySdamSubscriber.php @@ -0,0 +1,56 @@ +stream, + 'Server opening on %s:%s\n', + $event->getHost(), + $event->getPort(), + PHP_EOL, + ); + } + + public function serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent $event): void + { + } + + public function serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent $event): void + { + } + + public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent $event): void + { + } + + public function serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent $event): void + { + } + + public function serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent $event): void + { + } + + public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent $event): void + { + } + + public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent $event): void + { + } + + public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent $event): void + { + } +} +// end-sdam-subscriber \ No newline at end of file diff --git a/source/includes/monitoring-logging/logging.php b/source/includes/monitoring-logging/logging.php index c9d1a66d..7df5c778 100644 --- a/source/includes/monitoring-logging/logging.php +++ b/source/includes/monitoring-logging/logging.php @@ -13,9 +13,7 @@ // end-monolog-logger // start-custom-logger -use Psr\Log\AbstractLogger; - -class MyLogger extends AbstractLogger +class MyLogger extends Psr\Log\AbstractLogger { public array $logs = []; diff --git a/source/includes/monitoring-logging/monitor.php b/source/includes/monitoring-logging/monitor.php index 453c40da..b44b5e86 100644 --- a/source/includes/monitoring-logging/monitor.php +++ b/source/includes/monitoring-logging/monitor.php @@ -2,87 +2,8 @@ require __DIR__ . '/vendor/autoload.php'; -// start-command-subscriber -class MyCommandSubscriber implements MongoDB\Driver\Monitoring\CommandSubscriber -{ - /** @param resource $stream */ - public function __construct(private $stream) - { - } - - public function commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent $event): void - { - fwrite($this->stream, sprintf( - 'Started command #%d "%s": %s%s', - $event->getRequestId(), - $event->getCommandName(), - MongoDB\BSON\Document::fromPHP($event->getCommand())->toCanonicalExtendedJSON(), - PHP_EOL, - )); - } - - public function commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent $event): void - { - } - - public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent $event): void - { - } -} -// end-command-subscriber - -// start-sdam-subscriber -class MySDAMSubscriber implements MongoDB\Driver\Monitoring\SDAMSubscriber -{ - /** @param resource $stream */ - public function __construct(private $stream) - { - } - - public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent $event): void - { - fprintf( - $this->stream, - 'Server opening on %s:%s\n', - $event->getHost(), - $event->getPort(), - PHP_EOL, - ); - } - - public function serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent $event): void - { - } - - public function serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent $event): void - { - } - - public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent $event): void - { - } - - public function serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent $event): void - { - } - - public function serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent $event): void - { - } - - public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent $event): void - { - } - - public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent $event): void - { - } - - public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent $event): void - { - } -} -// end-sdam-subscriber +use Monitor\MyCommandSubscriber; +use Monitor\MySdamSubscriber; $uri = getenv('MONGODB_URI') ?: throw new RuntimeException('Set the MONGODB_URI variable to your connection URI'); $client = new MongoDB\Client($uri); diff --git a/source/monitoring-logging/monitoring.txt b/source/monitoring-logging/monitoring.txt index 71600b98..b930eef3 100644 --- a/source/monitoring-logging/monitoring.txt +++ b/source/monitoring-logging/monitoring.txt @@ -126,7 +126,7 @@ the ``CommandSubscriber`` interface. The class defines each ``CommandSubscriber` and includes custom logic for the ``commandStarted()`` method, which prints details about each new command that the server receives: -.. literalinclude:: /includes/monitoring-logging/monitor.php +.. literalinclude:: /includes/monitoring-logging/MyCommandSubscriber.php :start-after: start-command-subscriber :end-before: end-command-subscriber :language: php @@ -193,7 +193,7 @@ the ``SDAMSubscriber`` interface. The class defines each ``SDAMSubscriber`` meth and includes custom logic for the ``serverOpening()`` method, which prints details about servers added to the topology: -.. literalinclude:: /includes/monitoring-logging/monitor.php +.. literalinclude:: /includes/monitoring-logging/MySdamSubscriber.php :start-after: start-sdam-subscriber :end-before: end-sdam-subscriber :language: php From d4f27d7568c27cf2c24675f84a0c9c1a3af094f9 Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 2 Jul 2025 10:21:42 -0400 Subject: [PATCH 11/12] fix --- source/includes/monitoring-logging/MyCommandSubscriber.php | 2 +- source/includes/monitoring-logging/MySdamSubscriber.php | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/monitoring-logging/MyCommandSubscriber.php b/source/includes/monitoring-logging/MyCommandSubscriber.php index 5798aca3..1f50e6f1 100644 --- a/source/includes/monitoring-logging/MyCommandSubscriber.php +++ b/source/includes/monitoring-logging/MyCommandSubscriber.php @@ -29,4 +29,4 @@ public function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent $even { } } -// end-command-subscriber \ No newline at end of file +// end-command-subscriber diff --git a/source/includes/monitoring-logging/MySdamSubscriber.php b/source/includes/monitoring-logging/MySdamSubscriber.php index 4b9a77d7..52e49285 100644 --- a/source/includes/monitoring-logging/MySdamSubscriber.php +++ b/source/includes/monitoring-logging/MySdamSubscriber.php @@ -53,4 +53,4 @@ public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent $ { } } -// end-sdam-subscriber \ No newline at end of file +// end-sdam-subscriber From 2d6a52c8c340a962e2ee0f77f9a25970cdfebe8d Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 2 Jul 2025 11:27:09 -0400 Subject: [PATCH 12/12] RR feedback --- source/connect.txt | 265 ----------------- source/includes/authentication.php | 138 +++++++++ source/includes/connect/ca-file-tabs.rst | 2 +- .../usage-examples/connect-code-examples.php | 138 --------- source/security.txt | 269 +++++++++++++++++- 5 files changed, 406 insertions(+), 406 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index ccffe928..31d44565 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -132,271 +132,6 @@ The following code shows how to connect to a replica set deployment: To learn more about connecting to a replica set, see :ref:`php-connection-replica-set` in the Connection Targets guide. -Transport Layer Security (TLS) ------------------------------- - -Enable TLS -~~~~~~~~~~ - -The following code shows how to enable TLS for the connection to your -MongoDB instance: - -.. tabs:: - - .. tab:: MongoDB\\Client - :tabid: Client - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-enable-tls-client - :end-before: end-enable-tls-client - - .. tab:: Connection URI - :tabid: connectionstring - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-enable-tls-uri - :end-before: end-enable-tls-uri - -To learn more about enabling TLS, see :ref:`php-enable-tls` in -the TLS Configuration guide. - -Specify a Certificate Authority (CA) File -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following code shows how to specify the path to your CA file -for the connection to your MongoDB instance: - -.. tabs:: - - .. tab:: MongoDB\\Client - :tabid: Client - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-ca-file-client - :end-before: end-ca-file-client - - .. tab:: Connection URI - :tabid: connectionstring - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-ca-file-uri - :end-before: end-ca-file-uri - -To learn more about specifying a CA file, see :ref:`php-specify-ca-file` in -the TLS Configuration guide. - -Disable OCSP Checks -~~~~~~~~~~~~~~~~~~~ - -The following code shows how to prevent the driver from contacting -the OCSP endpoint: - -.. tabs:: - - .. tab:: MongoDB\\Client - :tabid: Client - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-disable-ocsp-client - :end-before: end-disable-ocsp-client - - .. tab:: Connection URI - :tabid: connectionstring - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-disable-ocsp-uri - :end-before: end-disable-ocsp-uri - -To learn more about disabling OCSP checks, see :ref:`php-disable-ocsp` in -the TLS Configuration guide. - -Specify a Certificate Revocation List (CRL) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following code shows how to instruct the driver to verify the server's -certificate against a CRL: - -.. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-crl - :end-before: end-crl - -To learn more about specifying a CRL, see :ref:`php-crl` in the TLS -configuration guide. - -Present a Client Certificate -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following code shows how to specify the client certificate that -the driver presents to your MongoDB deployment: - -.. tabs:: - - .. tab:: MongoDB\\Client - :tabid: Client - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-client-cert-client - :end-before: end-client-cert-client - - .. tab:: Connection URI - :tabid: connectionstring - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-client-cert-uri - :end-before: end-client-cert-uri - -To learn more about specifying a client certificate, see :ref:`php-client-cert` in -the TLS Configuration guide. - -Provide a Certificate Key File Password -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following code shows how to specify the password for your -client certificate: - -.. tabs:: - - .. tab:: MongoDB\\Client - :tabid: Client - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-key-file-client - :end-before: end-key-file-client - - .. tab:: Connection URI - :tabid: connectionstring - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-key-file-uri - :end-before: end-key-file-uri - -.. important:: - - When replacing the ```` placeholder in the connection URI, ensure - that you :wikipedia:`percent-encode ` the value. - -To learn more about providing a key file password, see :ref:`php-key-file-password` in -the TLS Configuration guide. - -Allow Insecure TLS -~~~~~~~~~~~~~~~~~~ - -The following code shows how to relax TLS constraints, which has the same -effect as disabling both :ref:`certificate validation ` -and :ref:`hostname verification `: - -.. tabs:: - - .. tab:: MongoDB\\Client - :tabid: Client - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-insecure-tls-client - :end-before: end-insecure-tls-client - - .. tab:: Connection URI - :tabid: connectionstring - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-insecure-tls-uri - :end-before: end-insecure-tls-uri - -To learn more about allowing insecure TLS, see :ref:`php-insecure-tls` in -the TLS Configuration guide. - -.. warning:: - - Setting the ``tlsInsecure`` option to ``true`` might expose your application - to security risks. Enabling this option makes your application insecure and - potentially vulnerable to expired certificates and to foreign processes posing - as valid client instances. - -.. _php-connect-disable-cert: - -Disable Certificate Validation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following code shows how to disable certificate validation: - -.. tabs:: - - .. tab:: MongoDB\\Client - :tabid: Client - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-disable-cert-client - :end-before: end-disable-cert-client - - .. tab:: Connection URI - :tabid: connectionstring - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-disable-cert-uri - :end-before: end-disable-cert-uri - -To learn more about disabling certificate validation, see :ref:`php-insecure-tls` in -the TLS Configuration guide. - -.. _php-connect-disable-hostname: - -Disable Hostname Verification -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following code shows how to disable hostname verification: - -.. tabs:: - - .. tab:: MongoDB\\Client - :tabid: Client - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-disable-hostname-client - :end-before: end-disable-hostname-client - - .. tab:: Connection URI - :tabid: connectionstring - - .. literalinclude:: /includes/usage-examples/connect-code-examples.php - :language: php - :dedent: - :start-after: start-disable-hostname-uri - :end-before: end-disable-hostname-uri - -To learn more about disabling hostname verification, see :ref:`php-insecure-tls` in -the TLS Configuration guide. - {+stable-api+} -------------- diff --git a/source/includes/authentication.php b/source/includes/authentication.php index d1ee266d..4270f0fa 100644 --- a/source/includes/authentication.php +++ b/source/includes/authentication.php @@ -105,3 +105,141 @@ $uri = 'mongodb://:/?authMechanism=MONGODB-AWS'; $client = new MongoDB\Client($uri); // end-mongodb-aws-env-uri + +// Connects to a MongoDB deployment and enables TLS using client +// options +// start-enable-tls-client +$client = new MongoDB\Client( + 'mongodb://:/', + ['tls' => true], +); +// end-enable-tls-client + +// Connects to a MongoDB deployment and enables TLS using connection URI +// parameters +// start-enable-tls-uri +$uri = 'mongodb://:/?tls=true'; +$client = new MongoDB\Client($uri); +// end-enable-tls-uri + +// Connects to a MongoDB deployment, enables TLS, and specifies the path to +// a CA file using client options +// start-ca-file-client +$client = new MongoDB\Client( + 'mongodb://:/', + ['tls' => true, 'tlsCAFile' => '/path/to/ca.pem'], +); +// end-ca-file-client + +// Connects to a MongoDB deployment, enables TLS, and specifies the path to +// a CA file using connection URI parameters +// start-ca-file-uri +$uri = 'mongodb://:/?tls=true&tlsCAFile=/path/to/ca.pem'; +$client = new MongoDB\Client($uri); +// end-ca-file-uri + +// Connects to a MongoDB deployment, enables TLS, and prevents OCSP endpoint checks +// using client options +// start-disable-ocsp-client +$client = new MongoDB\Client( + 'mongodb://:/', + ['tls' => true, 'tlsDisableOCSPEndpointCheck' => true], +); +// end-disable-ocsp-client + +// Connects to a MongoDB deployment, enables TLS, and prevents OCSP endpoint checks +// using connection URI parameters +// start-disable-ocsp-uri +$uri = 'mongodb://:/?tls=true&tlsDisableOCSPEndpointCheck=true'; +$client = new MongoDB\Client($uri); +// end-disable-ocsp-uri + +// Connects to a TLS-enabled deployment and instructs the driver to check the +// server certificate against a CRL +// start-crl +$client = new MongoDB\Client( + 'mongodb://:/', + ['tls' => true], + ['crl_file' => '/path/to/file.pem'], +); +// end-crl + +// Presents a client certificate to prove identity +// using client options +// start-client-cert-client +$client = new MongoDB\Client( + 'mongodb://:/', + ['tls' => true, 'tlsCertificateKeyFile' => '/path/to/client.pem'], +); +// end-client-cert-client + +// Presents a client certificate to prove identity +// using connection URI parameters +// start-client-cert-uri +$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem'; +$client = new MongoDB\Client($uri); +// end-client-cert-uri + +// Specifies the password for a client certificate using client options +// start-key-file-client +$client = new MongoDB\Client( + 'mongodb://:/', + [ + 'tls' => true, + 'tlsCertificateKeyFile' => '/path/to/client.pem', + 'tlsCertificateKeyFilePassword' => '', + ], +); +// end-key-file-client + +// Specifies the password for a client certificate using connection URI parameters +// start-key-file-uri +$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem&tlsCertificateKeyFilePassword='; +$client = new MongoDB\Client($uri); +// end-key-file-uri + +// Connects to a TLS-enabled deployment and disables server certificate verification +// using client options +// start-insecure-tls-client +$client = new MongoDB\Client( + 'mongodb://:/', + ['tls' => true, 'tlsInsecure' => true], +); +// end-insecure-tls-client + +// Connects to a TLS-enabled deployment and disables server certificate verification +// using connection URI parameters +// start-insecure-tls-uri +$uri = 'mongodb://:/?tls=true&tlsInsecure=true'; +$client = new MongoDB\Client($uri); +// end-insecure-tls-uri + +// Disables certificate validation using client options +// start-disable-cert-client +$client = new MongoDB\Client( + 'mongodb://:/', + ['tls' => true, 'tlsAllowInvalidCertificates' => true], +); +// end-disable-cert-client + +// Disables certificate validation using connection URI parameters +// start-disable-cert-uri +$uri = 'mongodb://:/?tls=true&tlsAllowInvalidCertificates=true'; +$client = new MongoDB\Client($uri); +// end-disable-cert-uri + +// Connects to a TLS-enabled deployment and disables hostname verification +// using client options +// start-disable-hostname-client +$client = new MongoDB\Client( + 'mongodb://:/', + ['tls' => true, 'tlsAllowInvalidHostnames' => true], +); +// end-disable-hostname-client + +// Connects to a TLS-enabled deployment and disables hostname verification +// using connection URI parameters +// start-disable-hostname-uri +$uri = 'mongodb://:/?tls=true&tlsAllowInvalidHostnames=true'; +$client = new MongoDB\Client($uri); +// end-disable-hostname-uri diff --git a/source/includes/connect/ca-file-tabs.rst b/source/includes/connect/ca-file-tabs.rst index 4cae5b03..7fa15dc5 100644 --- a/source/includes/connect/ca-file-tabs.rst +++ b/source/includes/connect/ca-file-tabs.rst @@ -9,7 +9,7 @@ $options = [ 'tls' => true, - 'tlsCAFile' => '/path/to/ca.pem' , + 'tlsCAFile' => '/path/to/ca.pem', ]; $client = new MongoDB\Client($uri, $options); diff --git a/source/includes/usage-examples/connect-code-examples.php b/source/includes/usage-examples/connect-code-examples.php index 82854aec..0d9da013 100644 --- a/source/includes/usage-examples/connect-code-examples.php +++ b/source/includes/usage-examples/connect-code-examples.php @@ -28,144 +28,6 @@ $client = new MongoDB\Client($uri); // end-replica-set-uri -// Connects to a MongoDB deployment and enables TLS using client -// options -// start-enable-tls-client -$client = new MongoDB\Client( - 'mongodb://:/', - ['tls' => true], -); -// end-enable-tls-client - -// Connects to a MongoDB deployment and enables TLS using connection URI -// parameters -// start-enable-tls-uri -$uri = 'mongodb://:/?tls=true'; -$client = new MongoDB\Client($uri); -// end-enable-tls-uri - -// Connects to a MongoDB deployment, enables TLS, and specifies the path to -// a CA file using client options -// start-ca-file-client -$client = new MongoDB\Client( - 'mongodb://:/', - ['tls' => true, 'tlsCAFile' => '/path/to/ca.pem'], -); -// end-ca-file-client - -// Connects to a MongoDB deployment, enables TLS, and specifies the path to -// a CA file using connection URI parameters -// start-ca-file-uri -$uri = 'mongodb://:/?tls=true&tlsCAFile=/path/to/ca.pem'; -$client = new MongoDB\Client($uri); -// end-ca-file-uri - -// Connects to a MongoDB deployment, enables TLS, and prevents OCSP endpoint checks -// using client options -// start-disable-ocsp-client -$client = new MongoDB\Client( - 'mongodb://:/', - ['tls' => true, 'tlsDisableOCSPEndpointCheck' => true], -); -// end-disable-ocsp-client - -// Connects to a MongoDB deployment, enables TLS, and prevents OCSP endpoint checks -// using connection URI parameters -// start-disable-ocsp-uri -$uri = 'mongodb://:/?tls=true&tlsDisableOCSPEndpointCheck=true'; -$client = new MongoDB\Client($uri); -// end-disable-ocsp-uri - -// Connects to a TLS-enabled deployment and instructs the driver to check the -// server certificate against a CRL -// start-crl -$client = new MongoDB\Client( - 'mongodb://:/', - ['tls' => true], - ['crl_file' => '/path/to/file.pem'], -); -// end-crl - -// Presents a client certificate to prove identity -// using client options -// start-client-cert-client -$client = new MongoDB\Client( - 'mongodb://:/', - ['tls' => true, 'tlsCertificateKeyFile' => '/path/to/client.pem'], -); -// end-client-cert-client - -// Presents a client certificate to prove identity -// using connection URI parameters -// start-client-cert-uri -$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem'; -$client = new MongoDB\Client($uri); -// end-client-cert-uri - -// Specifies the password for a client certificate using client options -// start-key-file-client -$client = new MongoDB\Client( - 'mongodb://:/', - [ - 'tls' => true, - 'tlsCertificateKeyFile' => '/path/to/client.pem', - 'tlsCertificateKeyFilePassword' => '', - ], -); -// end-key-file-client - -// Specifies the password for a client certificate using connection URI parameters -// start-key-file-uri -$uri = 'mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem&tlsCertificateKeyFilePassword='; -$client = new MongoDB\Client($uri); -// end-key-file-uri - -// Connects to a TLS-enabled deployment and disables server certificate verification -// using client options -// start-insecure-tls-client -$client = new MongoDB\Client( - 'mongodb://:/', - ['tls' => true, 'tlsInsecure' => true], -); -// end-insecure-tls-client - -// Connects to a TLS-enabled deployment and disables server certificate verification -// using connection URI parameters -// start-insecure-tls-uri -$uri = 'mongodb://:/?tls=true&tlsInsecure=true'; -$client = new MongoDB\Client($uri); -// end-insecure-tls-uri - -// Disables certificate validation using client options -// start-disable-cert-client -$client = new MongoDB\Client( - 'mongodb://:/', - ['tls' => true, 'tlsAllowInvalidCertificates' => true], -); -// end-disable-cert-client - -// Disables certificate validation using connection URI parameters -// start-disable-cert-uri -$uri = 'mongodb://:/?tls=true&tlsAllowInvalidCertificates=true'; -$client = new MongoDB\Client($uri); -// end-disable-cert-uri - -// Connects to a TLS-enabled deployment and disables hostname verification -// using client options -// start-disable-hostname-client -$client = new MongoDB\Client( - 'mongodb://:/', - ['tls' => true, 'tlsAllowInvalidHostnames' => true], -); -// end-disable-hostname-client - -// Connects to a TLS-enabled deployment and disables hostname verification -// using connection URI parameters -// start-disable-hostname-uri -$uri = 'mongodb://:/?tls=true&tlsAllowInvalidHostnames=true'; -$client = new MongoDB\Client($uri); -// end-disable-hostname-uri - // Connects to a MongoDB deployment and enables the stable API // start-stable-api $driverOptions = ['serverApi' => new MongoDB\Driver\ServerApi('1')]; diff --git a/source/security.txt b/source/security.txt index c300166c..1adb0496 100644 --- a/source/security.txt +++ b/source/security.txt @@ -29,7 +29,7 @@ Secure Your Data Overview -------- -MongoDB supports multiple mechanisms that you can use to authenticate your application. +MongoDB supports multiple mechanisms that secure your database connection. This page contains code examples that demonstrate each of these mechanisms. .. tip:: @@ -37,7 +37,7 @@ This page contains code examples that demonstrate each of these mechanisms. To learn more about any of the mechanisms shown on this page, see the link provided in each section. -To use an authentication example from this page, copy the code example into the +To use an example from this page, copy the code example into the :ref:`sample application ` or your own application. Make sure to replace all placeholders in the code examples, such as ````, with the relevant values for your MongoDB deployment. @@ -223,3 +223,268 @@ credentials, see the following sections in the Authentication guide: - :ref:`php-mongodb-aws-oidc` - :ref:`php-mongodb-aws-ecs` - :ref:`php-mongodb-aws-ec2` + +Transport Layer Security (TLS) +------------------------------ + +Enable TLS +~~~~~~~~~~ + +The following code shows how to enable TLS for the connection to your +MongoDB instance: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-enable-tls-client + :end-before: end-enable-tls-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-enable-tls-uri + :end-before: end-enable-tls-uri + +To learn more about enabling TLS, see :ref:`php-enable-tls` in +the TLS Configuration guide. + +Specify a Certificate Authority (CA) File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to specify the path to your CA file +for the connection to your MongoDB instance: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-ca-file-client + :end-before: end-ca-file-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-ca-file-uri + :end-before: end-ca-file-uri + +To learn more about specifying a CA file, see :ref:`php-specify-ca-file` in +the TLS Configuration guide. + +Disable OCSP Checks +~~~~~~~~~~~~~~~~~~~ + +The following code shows how to prevent the driver from contacting +the OCSP endpoint: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-disable-ocsp-client + :end-before: end-disable-ocsp-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-disable-ocsp-uri + :end-before: end-disable-ocsp-uri + +To learn more about disabling OCSP checks, see :ref:`php-disable-ocsp` in +the TLS Configuration guide. + +Specify a Certificate Revocation List (CRL) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to instruct the driver to verify the server's +certificate against a CRL: + +.. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-crl + :end-before: end-crl + +To learn more about specifying a CRL, see :ref:`php-crl` in the TLS +configuration guide. + +Present a Client Certificate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to specify the client certificate that +the driver presents to your MongoDB deployment: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-client-cert-client + :end-before: end-client-cert-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-client-cert-uri + :end-before: end-client-cert-uri + +To learn more about specifying a client certificate, see :ref:`php-client-cert` in +the TLS Configuration guide. + +Provide a Certificate Key File Password +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to specify the password for your +client certificate: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-key-file-client + :end-before: end-key-file-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-key-file-uri + :end-before: end-key-file-uri + +.. important:: + + When replacing the ```` placeholder in the connection URI, ensure + that you :wikipedia:`percent-encode ` the value. + +To learn more about providing a key file password, see :ref:`php-key-file-password` in +the TLS Configuration guide. + +Allow Insecure TLS +~~~~~~~~~~~~~~~~~~ + +The following code shows how to relax TLS constraints, which has the same +effect as disabling both :ref:`certificate validation ` +and :ref:`hostname verification `: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-insecure-tls-client + :end-before: end-insecure-tls-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-insecure-tls-uri + :end-before: end-insecure-tls-uri + +To learn more about allowing insecure TLS, see :ref:`php-insecure-tls` in +the TLS Configuration guide. + +.. warning:: + + Setting the ``tlsInsecure`` option to ``true`` might expose your application + to security risks. Enabling this option makes your application insecure and + potentially vulnerable to expired certificates and to foreign processes posing + as valid client instances. + +.. _php-connect-disable-cert: + +Disable Certificate Validation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to disable certificate validation: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-disable-cert-client + :end-before: end-disable-cert-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-disable-cert-uri + :end-before: end-disable-cert-uri + +To learn more about disabling certificate validation, see :ref:`php-insecure-tls` in +the TLS Configuration guide. + +.. _php-connect-disable-hostname: + +Disable Hostname Verification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code shows how to disable hostname verification: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-disable-hostname-client + :end-before: end-disable-hostname-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/authentication.php + :language: php + :dedent: + :start-after: start-disable-hostname-uri + :end-before: end-disable-hostname-uri + +To learn more about disabling hostname verification, see :ref:`php-insecure-tls` in +the TLS Configuration guide.