Table of Contents
Table 4.1. PHP Client Library Connection Methods
| Method | Title |
|---|---|
$object->getClientVersion() | Returns the version of the client library |
$object->getNumReplicas() | Returns the number of replicas for the configured bucket |
$object->getOption($option) | Retrieve an option |
$object->getVersion() | Returns the versions of all servers in the server pool |
$object->new Couchbase([ $url ] [, $username ] [, $password ] [, $bucket ] [, $persistent ]) | Create connection to Couchbase Server |
$object->setOption($option, $mixed) | Specify an option |
To connect to a Couchbase Server, you must should create a new
Couchbase object:
| API Call | $object->new Couchbase([ $url ] [, $username ] [, $password ] [, $bucket ] [, $persistent ]) | ||
| Asynchronous | no | ||
| Description | Create a connection to Couchbase Server with given parameters, such as node URL. The connection obtains the cluster configuration from the first host to which it has connected. Further communication operates directly with each node in the cluster as required. | ||
| Returns | scalar; supported values: | ||
object | New connection object to cluster | ||
| Arguments | |||
string $url | URL for Couchbase Server Instance, or node. | ||
| Default | localhost:8091 | ||
string $username | Username for Couchbase bucket. | ||
| Default | "(empty string)" | ||
string $password | Password for Couchbase bucket. | ||
| Default | "(empty string)" | ||
string $bucket | Bucket name used for storing objects. | ||
| Default | default | ||
string $persistent | True/false which indicates whether connection should be persistent or not. | ||
| Default | 0 (false) | ||
| Errors | |||
CouchbaseAuthenticationException | Authentication to the Couchbase cluster failed | ||
CouchbaseException | Base exception class for all Couchbase exceptions | ||
CouchbaseLibcouchbaseException | An error occurred within the libcouchbase library used by th PHP extension | ||
CouchbaseServerException | An error occurred within the Couchbase cluster | ||
An example below on creating a single connection to the default bucket at Couchbase Server:
$cb = new Couchbase("192.168.1.200:8091");For redundancy, you should specify more than one host to attempt the connection with the cluster. You can do this either by supplying a string a semi-colon separated list of hosts, for example:
$cb = new Couchbase("192.168.1.200:8091;192.168.1.206:8091");Alternatively, you can supply an array as the first argument:
$cb = new Couchbase(array("192.168.1.200:8091","192.168.1.206:8091"));The two formats are functionally identical.
To create a connection to a named bucket using SASL authentication, you must specify the bucket name, username (bucket name) and bucket password:
$cb = new Couchbase("192.168.1.200:8091", "logging", "pass", "logging");The Couchbase PHP SDK can also create a persistent connection which can be used for multiple request and response from processes. When you use a persistent connection, the first connection request from an SDK will take longer than subsequent SDK requests. Each subsequent request from a client application automatically reuses the existing instance of the client and the connections for that client. The following example demonstrates how you create a persistent connection:
$cb = new Couchbase("192.168.1.200:8091", "user", "pass", "bucket", true);The parameters you use include host:port, username, password, bucket name, and a boolean. The boolean set to true indicates that you want to create a persistent connection. By default connections are not persistent.
When you use a persistent connection, the first request from a client application will typically require more CPU and time to create a connection, compared to operations that rely on an existing connection. Subsequent requests from a client application will automatically reuse this existing persistent connection.
Be aware many web servers such as Apache will automatically take control of the connection instance and may destroy but also rebuild a connection after a certain number of requests. This is part of the web server functioning, and enables the web server to create a pool of reuseable connections.