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..22a1d850 --- /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 {+library-short+} 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 + deployment that the {+library-short+} is connected to. + +.. _php-enable-compression: + +Enable Network Compression +-------------------------- + +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: + +- 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/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