A newer version of this documentation is available.

View Latest

Managing Connections Using the PHP SDK with Couchbase Server

    This section describes how to connect the PHP SDK to a Couchbase cluster and bucket. It contains best practices as well as information on the connection string, SSL and other advanced connection options.

    To manage Couchbase Server connections, you need to configure the client, connect to a bucket, and configure SSL.

    Configuring the Client

    To configure the client, instantiate a new Cluster object:

    $myCluster = new CouchbaseCluster('couchbase://,,');
    Any Cluster nodes addresses passed in to the Cluster object, to establish (bootstrap) the connection, should be for data (KV) nodes.

    In addition to the connection string passed to the Cluster object, you can include a username and password. The username and password are required to perform management operations against your cluster. If you do not use the cluster management aspects of the SDK, the username and password parameters are optional. Keep in mind that these credentials are the same ones you use to log in to the Couchbase administrator console, not those specified for the bucket itself.

    From Couchbase PHP SDK 2.5.0 (using libcouchbase 2.9.2), AlternateAddress is implemented, for connecting to nodes in a NATed environment, such as Docker containers using portmapping. It is on by default, if the server provides a topology that includes a multi-network configuration. Whichever network is selected at bootstrap will be logged.

    If using Docker Swarm, or otherwise running the SDK inside the NAT, then you will want to disable with ?network=default in the connection string, or an environmental setting can be made. For more details, see the libcouchbase notes.

    Note that any SSL/TLS certificates must be set up at the point where the connections are being made. The Couchbase SDKs will honor any valid SSL/TLS certificates.


    Regular authentication is where you provide a password to the openBucket() and manager() methods. It is also possible to define all credentials in single place, and associate with a container, which can be used for all future connections.

    Since version 2.3.0, the PHP SDK provides the interface \Couchbase\Authenticator which is implemented by all credentials containers. The library can pull authentication parameters from it when necessary. At the moment there is only one implementation of this interface: \Couchbase\ClassicAuthenticator, but upcoming releases will also have RBAC support. The use of the authenticator is simple:

    $authenticator = new \Couchbase\ClassicAuthenticator();
    $authenticator->cluster('Administrator', 'password');
    $authenticator->bucket('protected', 'secret');
    $cluster = new \Couchbase\Cluster("couchbase://localhost");
    $cluster->openBucket('protected'); // successfully opens connection
    $cluster->manager()->createBucket('hello'); // automatically use admin credentials

    It is still possible to provide a password to the openBucket() or manager() method, which will take precedence over the authenticator. Such behaviour is discouraged, and future implementations of the \Couchbase\Authenticator interface are likely to prevent mixing of authentication sources.

    You can shortcut using the authenticator() method, if you don’t need to reuse the credentials in several instances of authenticate(), replacing it with authenticateAs():

    $cluster = new CouchbaseCluster("couchbase://localhost");
    $cluster->authenticateAs('Administrator', 'password');

    Connecting to a Bucket

    To connect to a bucket, call the openBucket() method against your Cluster instance, passing in the name of the bucket that you want to connect to. The following example shows how to connect to a bucket (here named testBucket):

    $myCluster = new CouchbaseCluster();
    $myBucket = $myCluster->openBucket('testBucket');

    In addition to the bucket name, you can optionally include the bucket password if one has been defined, as shown in the following example:

    $myCluster = new CouchbaseCluster();
    $myBucket = $myCluster->openBucket('testBucket', 'password');

    Scalability and concurrency

    Creating a new Bucket object is relatively expensive, and keeping many idle Bucket objects will negatively impact server performance (if done at a large scale).

    PHP SDK by default uses persistent connections to reuse underlying IO objects if the connection strings are the same.

    Connection Limits

    Each Couchbase Data node allows by default, in Couchbase Data Platform 6.0 and earlier, up to 30,000 concurrent key-value connections per port exposed to the user by the Data Service (ports 11210 and 11207). This means that if you are mixing SSL connections (port 11207) and plain connections (port 11210), you can have 30,000 connections on each of these two ports, or up to 60,000 in total. If you are using plain (or SSL) alone, then the limit is 30,000.

    From 6.5 onwards, the default value is 65,000 connections to the server — with 5000 of these reserved for system use. Thus, you can use 60,000 connections even if you only use_ one_ of the two ports (plain or SSL).

    Unresolved include directive in modules/ROOT/pages/managing-connections.adoc - include::2.8@c-sdk::page$managing-connections.adoc[]