Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Install and Start Using the PHP SDK with Couchbase Server

      +
      Installing the Couchbase PHP SDK & a Hello World example program.

      The Couchbase PHP SDK allows you to connect to a Couchbase cluster from PHP. It is a native PHP extension and uses the Couchbase++ high-performance C++ library to handle communicating to the cluster over Couchbase binary protocols.

      Hello Couchbase

      On this page we show you how to quickly get up and running — installing the Couchbase PHP SDK, and trying out the Hello World code example against Couchbase Capella, or against a local Couchbase cluster.

      We will go through the code sample step by step, but for those in a hurry to see it, here it is:

      • Couchbase Capella Sample

      • Local Couchbase Server

      If you are connecting to Couchbase Capella, be sure to get the correct endpoint as well as the username and password.

      <?php

// NOTE: Change the below vendor path to your own.
require_once '../../../vendor/autoload.php';

use Couchbase\ClusterOptions;
use Couchbase\Cluster;

// Update these credentials for your Capella instance!
$connectionString = "couchbases://cb.<your-instance>.cloud.couchbase.com";
$options = new ClusterOptions();

$options->credentials("username", "Password!123");
$options->keyValueTimeout(10 * 1000);
$cluster = new Cluster($connectionString, $options);

// get a bucket reference
$bucket = $cluster->bucket("travel-sample");

// get a user-defined collection reference
$scope = $bucket->scope("tenant_agent_00");
$collection = $scope->collection("users");

$upsertResult = $collection->upsert("my-document-key", ["name" => "Ted", "Age" => 31]);

$getResult = $collection->get("my-document-key");

print_r($getResult->content());

$queryResult = $cluster->query("select \"Hello World\" as greeting");

// Iterate over the rows to access result data and print to the terminal.
foreach ($queryResult->rows() as $row) {
    printf("%s\n", $row["greeting"]);
}

      The Couchbase Capella free tier version comes with the Travel Sample Bucket, and its Query indexes, loaded and ready.

      <?php

// NOTE: Change the below vendor path to your own.
require_once '../../../vendor/autoload.php';

use Couchbase\ClusterOptions;
use Couchbase\Cluster;

// Update these credentials for your Local instance!
$connectionString = "couchbase://localhost";
$options = new ClusterOptions();

$options->credentials("Administrator", "password");
$cluster = new Cluster($connectionString, $options);

// get a bucket reference
$bucket = $cluster->bucket("travel-sample");

// get a user-defined collection reference
$scope = $bucket->scope("tenant_agent_00");
$collection = $scope->collection("users");

$upsertResult = $collection->upsert("my-document-key", ["name" => "Ted", "Age" => 31]);

$getResult = $collection->get("my-document-key");

print_r($getResult->content());

$queryResult = $cluster->query("select \"Hello World\" as greeting");

// Iterate over the rows to access result data and print to the terminal.
foreach ($queryResult->rows() as $row) {
    printf("%s\n", $row["greeting"]);
}

      As well as the PHP SDK (see below), and a running instance of Couchbase Server, you will need to load up the Travel Sample Bucket using either the Web interface or the command line.

      Quick Installation

      A more detailed guide in our Installation page covers every supported platform, but this section should be enough to get up and running in most cases.

      • Mac and Linux

      • Alpine Linux

      • Windows

      On Mac and most Linux distributions, simply use pecl to install the Couchbase PHP SDK.

      $ pecl install couchbase

      Alpine Linux is very slim and uses musl libc and the apk package manager. As a result, the installation is a little different from other Unix-Like systems and pecl equivalent packages are used instead.

      $ apk add php7-pecl-couchbase

      Windows downloads and instructions for the PHP SDK are available from the installation page.

      Make sure to add the extension details to your php.ini. See post-installation instructions for full details:

      extension=json      ; not needed with PHP 8.0.0+
extension=couchbase

      Additionally, if you are using Composer, simply update your composer.json file with the following dependencies:

      "require": {
  ...
  "ext-couchbase": "^4.0",
  "couchbase/couchbase": "^4.0"
}

      And run the composer update command. If there are any problems, refer to the full Installation page.

      Step-by-step

      Start a new project (in VS Code or PhpStorm, etc.) and create a file cb-test.php.

      Go to our Platform Introduction if you don’t already have an editor or IDE setup for working with PHP — e.g. you are evaluating the PHP SDK, but it is not your normal platform.

      Prerequisites

      Install the latest 4.x couchbase SDK package — see above.

      The following code samples assume:

      • Couchbase Capella cluster, or Couchbase Server is installed and accessible locally (Do a Quick Install if you don’t already have Couchbase Server installed).

      • You have create a bucket (perhaps using the travel-sample dataset, or by creating a new bucket). Note, the Travel Sample dataset is installed automatically when deploying a Capella free tier cluster.

      • You have created a Couchbase user named "username" [change as appropriate] with permissions to access the cluster (at least Application Access permissions).

      Couchbase uses Role Based Access Control (RBAC) to control access to resources. Here we will use the Full Admin role created during installation of the Couchbase Data Platform. For production client code, you will want to use more appropriate, restrictive settings, but here we want to get you up and running quickly. If you’re developing client code on the same VM or machine as the Couchbase Server, your URI can be localhost.

      Firstly, you will need to have a few import statements at the top of your PHP program:

      // NOTE: Change the below vendor path to your own.
require_once '../../../vendor/autoload.php';

use Couchbase\ClusterOptions;
use Couchbase\Cluster;

      Connection

      Then you can connect to the cluster:

      • Capella Connection

      • Local Server Connection

      // Update these credentials for your Capella instance!
$connectionString = "couchbases://cb.<your-instance>.cloud.couchbase.com";
$options = new ClusterOptions();

$options->credentials("username", "Password!123");
$options->keyValueTimeout(10 * 1000);
$cluster = new Cluster($connectionString, $options);

      From 4.0, the PHP SDK includes Capella’s standard certificates by default, so you do not need to additional configuration. You do need to enable TLS, which can be done by simply using couchbases: in the Connection String as in this example.

      // Update these credentials for your Local instance!
$connectionString = "couchbase://localhost";
$options = new ClusterOptions();

$options->credentials("Administrator", "password");
$cluster = new Cluster($connectionString, $options);

      For developing locally on the same machine as the Couchbase Server, your URI can be couchbase://localhost as here. But for Production deployments, you will want to use a secure server, with couchbases://.

      See Managing Connections for full configuration details.

      Couchbase uses Role Based Access Control (RBAC) to control access to resources.

      Bucket, Scopes, and Collections

      Open the bucket:

      // get a bucket reference
$bucket = $cluster->bucket("travel-sample");

      Collections allow Documents to be grouped by purpose or theme, according to specified Scope. Our Travel Sample bucket has separate scopes for inventory (flights, etc.), and for tenants (different travel agents).

      // get a user-defined collection reference
$scope = $bucket->scope("tenant_agent_00");
$collection = $scope->collection("users");

      To get you started the following code creates a new document in a custom scope and collection and then fetches it again, printing the result.

      $upsertResult = $collection->upsert("my-document-key", ["name" => "Ted", "Age" => 31]);

$getResult = $collection->get("my-document-key");

print_r($getResult->content());

      Other possible key/value CRUD Operations are described in detail on the KV Operations page.

      You can also perform a N1QL query with the cluster object:

      $queryResult = $cluster->query("select \"Hello World\" as greeting");

// Iterate over the rows to access result data and print to the terminal.
foreach ($queryResult->rows() as $row) {
    printf("%s\n", $row["greeting"]);
}

      You can learn more about N1QL queries on the Query page.

      Next Steps

      Now you’re up and running, try one of the following:

      Additional Resources

      The API reference is generated for each release and can be found here. Older API references are linked from their respective sections in the Release Notes.

      The Migrating to SDK API 3 page highlights the main differences to be aware of when migrating your code.

      Couchbase welcomes community contributions to the PHP SDK. The PHP SDK source code is available on GitHub.

      Troubleshooting