DOCSP-47057: Network compression

source/connect/connection-options.txt

@@ -20,10 +20,7 @@ Specify Connection Options
 .. toctree::
 
    Stable API </connect/connection-options/stable-api>
-
-.. TODO:
    Compress Network Traffic </connect/connection-options/network-compression>
-   Connection Pools </connect/connection-options/connection-pools>
 
 Overview
 --------

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 {+library-short+} supports the following compressors:
+
+1. `Snappy <https://google.github.io/snappy/>`__
+#. `Zlib <https://zlib.net/>`__
+#. `Zstandard <https://github.com/facebook/zstd/>`__
+
+.. 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 </manual/en/mongodb-driver-manager.construct.php#refsect1-mongodb-driver-manager.construct-parameters>`
+in the extension API documentation.
+

source/includes/connect/network-compression.php

@@ -0,0 +1,30 @@
+<?php
+
+// start-enable-client
+$client = new MongoDB\Client(
+    'mongodb://<hostname>:<port>',
+    ['compressors' => 'snappy,zstd,zlib'],
+ );
+// end-enable-client
+
+// start-enable-uri
+$uri = 'mongodb://<hostname>:<port>/?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://<hostname>:<port>',
+    $uriOptions,
+);
+// end-set-level-client
+
+// start-set-level-uri
+$uri = 'mongodb://<hostname>:<port>/?compressors=zlib&zlibCompressionLevel=1';
+$client = new MongoDB\Client($uri);
+// end-set-level-uri