Add documentation CouchbaseBucketAdapter for cache system.

ajcerezo · ajcerezo · commit 5eb942c3b609 · 2019-06-14T09:54:11.000+02:00
diff --git a/components/cache/adapters/couchbasebucket_adapter.rst b/components/cache/adapters/couchbasebucket_adapter.rst
@@ -0,0 +1,135 @@
+.. index::
+    single: Cache Pool
+    single: Couchabase Cache
+
+.. _couchbase-adapter:
+
+Couchbase Cache Adapter
+=======================
+
+This adapter stores the values in-memory using one (or more) `Couchbase server`_
+instances. Unlike the :ref:`APCu adapter <apcu-adapter>`, and similarly to the
+:ref:`Memcached adapter <memcached-adapter>`, it is not limited to the current server's
+shared memory; you can store contents independent of your PHP environment.
+The ability to utilize a cluster of servers to provide redundancy and/or fail-over
+is also available.
+
+.. caution::
+
+    **Requirements:** The `Couchbase PHP extension`_ as well as a `Couchbase server`_
+    must be installed, active, and running to use this adapter. Version ``2.6`` or
+    greater of the `Couchbase PHP extension`_ is required for this adapter.
+
+This adapter expects a `Couchbase Bucket`_ instance to be passed as the first
+parameter. A namespace and default cache lifetime can optionally be passed as
+the second and third parameters::
+
+    use Symfony\Component\Cache\Adapter\CouchbaseBucketAdapter;
+
+    $cache = new CouchbaseBucketAdapter(
+        // the client object that sets options and adds the server instance(s)
+        \CouchbaseCluster $client,
+
+        // the name of bucket
+        string $bucket,
+
+        // a string prefixed to the keys of the items stored in this cache
+        $namespace = '',
+
+        // the default lifetime (in seconds) for cache items that do not define their
+        // own lifetime, with a value 0 causing items to be stored indefinitely (i.e.
+        // until MemcachedAdapter::clear() is invoked or the server(s) are restarted)
+        $defaultLifetime = 0,
+
+        // associative array of configuration options
+        array $options = [
+            'operationTimeout' => 10,
+            'configTimeout' => 5,
+            'configNodeTimeout' => 20,
+        ]
+    );
+
+
+Available Options
+~~~~~~~~~~~~~~~~~
+
+``operationTimeout`` (type: ``int``, default: ``2500000``)
+    The operation timeout (in microseconds) is the maximum amount of time the library will
+    wait for an operation to receive a response before invoking its callback with a failure status.
+
+``configTimeout`` (type: ``int``, default: ``5000000``)
+    How long (in microseconds) the client will wait to obtain the initial configuration.
+
+``configNodeTimeout`` (type: ``int``, default: ``2000000``)
+    Per-node configuration timeout (in microseconds).
+
+Configure the Connection
+------------------------
+
+The :method:`Symfony\\Component\\Cache\\Adapter\\CouchbaseBucketAdapter::createConnection`
+helper method allows creating and configuring a `Couchbase Bucket`_ class instance using a
+`Data Source Name (DSN)`_ or an array of DSNs::
+
+    use Symfony\Component\Cache\Adapter\CouchbaseBucketAdapter;
+
+    // pass an array of DSN strings to register multiple servers with the client
+    $client = MemcachedAdapter::createConnection([
+        'couchbase://10.0.0.100',
+        'couchbase://10.0.0.101',
+        'couchbase://10.0.0.102',
+        // etc...
+    ]);
+
+    // a single DSN can define multiple servers using the following syntax:
+    // host[hostname-or-IP:port] (where port is optional). Sockets must include a trailing ':'
+    $client = MemcachedAdapter::createConnection(
+        'couchbase:?host[localhost]&host[localhost:12345]&host[/some/memcached.sock:]=3'
+    );
+
+
+Configure the Options
+---------------------
+
+The :method:`Symfony\\Component\\Cache\\Adapter\\CouchbaseBucketAdapter::createConnection`
+helper method also accepts an array of options as its second argument. The
+expected format is an associative array of ``key => value`` pairs representing
+option names and their respective values::
+
+    use Symfony\Component\Cache\Adapter\CouchbaseBucketAdapter;
+
+    $client = MemcachedAdapter::createConnection(
+        // a DSN string or an array of DSN strings
+        [],
+
+        // associative array of configuration options
+        [
+            'username' => 'xxxxxx',
+            'password' => 'yyyyyy',
+        ]
+    );
+
+Available Options
+~~~~~~~~~~~~~~~~~
+
+``username`` (type: ``string``, default: ````)
+    Username for connection ``CoucbaseCluster``.
+
+``password`` (type: ``string``, default: ````)
+    Password of connection ``CouchbaseCluster``.
+
+
+.. tip::
+
+    Reference the `Memcached`_ extension's `predefined constants`_ documentation
+    for additional information about the available options.
+
+.. _`Transmission Control Protocol (TCP)`: https://en.wikipedia.org/wiki/Transmission_Control_Protocol
+.. _`User Datagram Protocol (UDP)`: https://en.wikipedia.org/wiki/User_Datagram_Protocol
+.. _`no-delay`: https://en.wikipedia.org/wiki/TCP_NODELAY
+.. _`keep-alive`: https://en.wikipedia.org/wiki/Keepalive
+.. _`Couchbase PHP extension`: https://docs.couchbase.com/sdk-api/couchbase-php-client-2.6.0/files/couchbase.html
+.. _`predefined constants`: http://php.net/manual/en/memcached.constants.php
+.. _`Couchbase server`: https://couchbase.com/
+.. _`Couchbase Bucket`: https://docs.couchbase.com/sdk-api/couchbase-php-client-2.6.0/classes/Couchbase.Bucket.html
+.. _`Data Source Name (DSN)`: https://en.wikipedia.org/wiki/Data_source_name
+.. _`Domain Name System (DNS)`: https://en.wikipedia.org/wiki/Domain_Name_System
