From 22270b3431d9f1ca875a95c304bc96ed8f068a42 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 22 May 2025 15:31:54 -0400 Subject: [PATCH 1/4] DOCSP-47057: Network compression --- source/connect/connection-options.txt | 3 - .../network-compression.txt | 123 ++++++++++++++++++ source/includes/connect/compression-tabs.rst | 19 +++ .../includes/connect/network-compression.php | 30 +++++ 4 files changed, 172 insertions(+), 3 deletions(-) create mode 100644 source/connect/connection-options/network-compression.txt create mode 100644 source/includes/connect/compression-tabs.rst create mode 100644 source/includes/connect/network-compression.php diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 2a20d0a8..54868fec 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -20,10 +20,7 @@ Specify Connection Options .. toctree:: Stable API - -.. TODO: Compress Network Traffic - Connection Pools Overview -------- diff --git a/source/connect/connection-options/network-compression.txt b/source/connect/connection-options/network-compression.txt new file mode 100644 index 00000000..b1b04fa6 --- /dev/null +++ b/source/connect/connection-options/network-compression.txt @@ -0,0 +1,123 @@ +.. _php-network-compression: + +======================== +Compress Network Traffic +======================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: zlib, zstandard, zstd, snappy + +Overview +-------- + +In this guide, you can learn how to configure **network compression** for +your connection to MongoDB. + +Network compression is a feature that allows you to compress and +decompress messages sent between your application and MongoDB, reducing +the total amount of data passed over the network. + +The driver supports the following compressors: + +1. `Snappy `__ +#. `Zlib `__ +#. `Zstandard `__ + +.. note:: Compressor Selection + + If you specify multiple compressors to use on your connection, the + driver selects the first one that is supported by the MongoDB + instance that the {+library-short+} is connected to. + +.. _php-enable-compression: + +Enable Network Compression +-------------------------- + +To enable compression for the connection to your MongoDB instance, use the +``compressors`` connection option and specify the compression algorithms you want to use. +You can do this in two ways: + +- Pass the algorithms as an argument to the ``MongoDB\Client`` constructor. +- Specify the algorithms in your connection string. + +The following example shows how to specify Snappy, Zlib, and +Zstandard as the compressors for a connection. Select the :guilabel:`MongoDB\Client` +or :guilabel:`Connection URI` tab to see the corresponding code: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/connect/network-compression.php + :language: php + :dedent: + :start-after: start-enable-client + :end-before: end-enable-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/connect/network-compression.php + :language: php + :dedent: + :start-after: start-enable-uri + :end-before: end-enable-uri + +Specify the zlib Compression Level +---------------------------------- + +If you specify ``zlib`` as one of your compression algorithms, you can also use the +``zlibCompressionLevel`` option to specify a compression level. This option accepts +an integer value between ``-1`` and ``9``: + +- **-1:** (Default). zlib uses its default compression level (usually ``6``). +- **0:** No compression. +- **1:** Fastest speed but lowest compression. +- **9:** Best compression but slowest speed. + +The following example specifies the ``zlib`` compression algorithm and a +``zlibCompressionLevel`` value of ``1``. Select the :guilabel:`MongoDB\Client` +or :guilabel:`Connection URI` tab to see the corresponding code: + +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: Client + + .. literalinclude:: /includes/connect/network-compression.php + :language: php + :dedent: + :start-after: start-set-level-client + :end-before: end-set-level-client + + .. tab:: Connection URI + :tabid: connectionstring + + .. literalinclude:: /includes/connect/network-compression.php + :language: php + :dedent: + :start-after: start-set-level-uri + :end-before: end-set-level-uri + +API Documentation +----------------- + +To learn more about the ``MongoDB\Client`` class, see :phpclass:`MongoDB\Client` +in the library API documentation. + +To view a full list of URI options that you can pass to a ``MongoDB\Client``, see the +:php:`MongoDB\Driver\Manager::__construct parameters ` +in the extension API documentation. + \ No newline at end of file diff --git a/source/includes/connect/compression-tabs.rst b/source/includes/connect/compression-tabs.rst new file mode 100644 index 00000000..f1142786 --- /dev/null +++ b/source/includes/connect/compression-tabs.rst @@ -0,0 +1,19 @@ +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: mongoclient + + .. code-block:: php + + $client = new MongoDB\Client( + 'mongodb://:', + ['compressors' => 'snappy,zstd,zlib'], + ); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = 'mongodb://:/?compressors=snappy,zstd,zlib'; + $client = new MongoDB\Client($uri); \ No newline at end of file diff --git a/source/includes/connect/network-compression.php b/source/includes/connect/network-compression.php new file mode 100644 index 00000000..26628509 --- /dev/null +++ b/source/includes/connect/network-compression.php @@ -0,0 +1,30 @@ +:', + ['compressors' => 'snappy,zstd,zlib'], + ); +// end-enable-client + +// start-enable-uri +$uri = 'mongodb://:/?compressors=snappy,zstd,zlib'; +$client = new MongoDB\Client($uri); +// end-enable-uri + +// start-set-level-client +$uriOptions = [ + 'compressors' => 'zlib', + 'zlibCompressionLevel' => 1, +]; + +$client = new MongoDB\Client( + 'mongodb://:', + $uriOptions, +); +// end-set-level-client + +// start-set-level-uri +$uri = 'mongodb://:/?compressors=zlib&zlibCompressionLevel=1'; +$client = new MongoDB\Client($uri); +// end-set-level-uri \ No newline at end of file From f09d42cca9264f2a91dd06b54b3bb941758708da Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 22 May 2025 15:33:11 -0400 Subject: [PATCH 2/4] delete --- source/includes/connect/compression-tabs.rst | 19 ------------------- 1 file changed, 19 deletions(-) delete mode 100644 source/includes/connect/compression-tabs.rst diff --git a/source/includes/connect/compression-tabs.rst b/source/includes/connect/compression-tabs.rst deleted file mode 100644 index f1142786..00000000 --- a/source/includes/connect/compression-tabs.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. tabs:: - - .. tab:: MongoDB\\Client - :tabid: mongoclient - - .. code-block:: php - - $client = new MongoDB\Client( - 'mongodb://:', - ['compressors' => 'snappy,zstd,zlib'], - ); - - .. tab:: Connection String - :tabid: connectionstring - - .. code-block:: php - - $uri = 'mongodb://:/?compressors=snappy,zstd,zlib'; - $client = new MongoDB\Client($uri); \ No newline at end of file From 266f5f1916dcdb4108918d23a89d5b32acdc631f Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 22 May 2025 15:40:03 -0400 Subject: [PATCH 3/4] edits --- source/connect/connection-options/network-compression.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/connect/connection-options/network-compression.txt b/source/connect/connection-options/network-compression.txt index b1b04fa6..34bf9a69 100644 --- a/source/connect/connection-options/network-compression.txt +++ b/source/connect/connection-options/network-compression.txt @@ -27,7 +27,7 @@ Network compression is a feature that allows you to compress and decompress messages sent between your application and MongoDB, reducing the total amount of data passed over the network. -The driver supports the following compressors: +The {+library-short+} supports the following compressors: 1. `Snappy `__ #. `Zlib `__ @@ -52,7 +52,7 @@ You can do this in two ways: - Specify the algorithms in your connection string. The following example shows how to specify Snappy, Zlib, and -Zstandard as the compressors for a connection. Select the :guilabel:`MongoDB\Client` +Zstandard as the compressors for a connection. Select the :guilabel:`MongoDB\\Client` or :guilabel:`Connection URI` tab to see the corresponding code: .. tabs:: @@ -88,7 +88,7 @@ an integer value between ``-1`` and ``9``: - **9:** Best compression but slowest speed. The following example specifies the ``zlib`` compression algorithm and a -``zlibCompressionLevel`` value of ``1``. Select the :guilabel:`MongoDB\Client` +``zlibCompressionLevel`` value of ``1``. Select the :guilabel:`MongoDB\\Client` or :guilabel:`Connection URI` tab to see the corresponding code: .. tabs:: From fa05dc11242273117c000a92ff5c30d0430bb3e0 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 22 May 2025 15:50:24 -0400 Subject: [PATCH 4/4] MM feedback --- source/connect/connection-options/network-compression.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/connect/connection-options/network-compression.txt b/source/connect/connection-options/network-compression.txt index 34bf9a69..22a1d850 100644 --- a/source/connect/connection-options/network-compression.txt +++ b/source/connect/connection-options/network-compression.txt @@ -37,14 +37,14 @@ The {+library-short+} supports the following compressors: If you specify multiple compressors to use on your connection, the driver selects the first one that is supported by the MongoDB - instance that the {+library-short+} is connected to. + deployment that the {+library-short+} is connected to. .. _php-enable-compression: Enable Network Compression -------------------------- -To enable compression for the connection to your MongoDB instance, use the +To enable compression for the connection to your MongoDB deployment, use the ``compressors`` connection option and specify the compression algorithms you want to use. You can do this in two ways: