.. index::
    single: Cache Pool
    single: Couchabase Cache

.. _couchbase-adapter:

Couchbase Cache Adapter
=======================

.. versionadded:: 5.1

    The CouchbaseBucketAdapter was introduced in Symfony 5.1.

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)
        \CouchbaseBucket $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
        $defaultLifetime = 0,
    );


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 a single DSN string to register a single server with the client
    $client = CouchbaseBucketAdapter::createConnection(
        'couchbase://localhost'
        // the DSN can include config options (pass them as a query string):
        // 'couchbase://localhost:11210?operationTimeout=10'
        // 'couchbase://localhost:11210?operationTimeout=10&configTimout=20'
    );

    // pass an array of DSN strings to register multiple servers with the client
    $client = CouchbaseBucketAdapter::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 = CouchbaseBucketAdapter::createConnection(
        'couchbase:?host[localhost]&host[localhost:12345]'
    );


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 = CouchbaseBucketAdapter::createConnection(
        // a DSN string or an array of DSN strings
        [],

        // associative array of configuration options
        [
            'username' => 'xxxxxx',
            'password' => 'yyyyyy',
            'configTimeout' => '100',
        ]
    );

Available Options
~~~~~~~~~~~~~~~~~

``username`` (type: ``string``)
    Username for connection ``CoucbaseCluster``.

``password`` (type: ``string``)
    Password of connection ``CouchbaseCluster``.

``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).

``viewTimeout`` (type: ``int``, default: ``75000000``)
    The I/O timeout (in microseconds) for HTTP requests to Couchbase Views API.

``httpTimeout`` (type: ``int``, default: ``75000000``)
    The I/O timeout (in microseconds) for HTTP queries (management API).

``configDelay`` (type: ``int``, default: ``10000``)
    Config refresh throttling
    Modify the amount of time (in microseconds) before the configiration error threshold will forcefully be set to its maximum number forcing a configuration refresh.

``htconfigIdleTimeout`` (type: ``int``, default: ``4294967295``)
    Idling/Persistence for HTTP bootstrap (in microseconds).

``durabilityInterval`` (type: ``int``, default: ``100000``)
    The time (in microseconds) the client will wait between repeated probes to a given server.

``durabilityTimeout`` (type: ``int``, default: ``5000000``)
    The time (in microseconds) the client will spend sending repeated probes to a given key's vBucket masters and replicas before they are deemed not to have satisfied the durability requirements.

.. tip::

    Reference the `Couchbase Bucket`_ extension's `predefined constants`_ documentation
    for additional information about the available options.

.. _`Couchbase PHP extension`: https://docs.couchbase.com/sdk-api/couchbase-php-client-2.6.0/files/couchbase.html
.. _`predefined constants`: https://docs.couchbase.com/sdk-api/couchbase-php-client-2.6.0/classes/Couchbase.Bucket.html
.. _`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