Install and Start Using the PHP SDK with Couchbase Server

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

Installing on Linux

For installation on Linux, install the couchbase-release repository, and then install the libcouchbase packages. The following examples download and install couchbase-release repsitory, a C and C++ compiler, the C SDK development files (libcouchbase-devel [RPM] or libcouchbase-dev [DEB]), PHP development files, and finally the PHP SDK using pecl.

Debian and Ubuntu

# Only needed during first-time setup:
wget http://packages.couchbase.com/releases/couchbase-release/couchbase-release-1.0-2-amd64.deb
sudo dpkg -i couchbase-release-1.0-2-amd64.deb
# Will install or upgrade packages
sudo apt-get update
sudo apt-get install libcouchbase-dev build-essential php-dev
sudo pecl install couchbase

RHEL and CentOS

# Only needed during first-time setup:
wget http://packages.couchbase.com/releases/couchbase-release/couchbase-release-1.0-2-x86_64.rpm
sudo rpm -iv couchbase-release-1.0-2-x86_64.rpm
# Will install or upgrade existing packages
sudo yum install libcouchbase-devel gcc gcc-c++ php-devel
sudo pecl install couchbase

Installation on Mac OS X

To install the library on Mac OS X, first install the de-facto package manager for OS X: homebrew. Once homebrew is configured:

brew update # get list of latest packages
brew install libcouchbase
# brew install homebrew/php/php{XY}-couchbase, where XY is your version of PHP
brew install homebrew/php/php70-couchbase # for PHP 7.0

If you have PECL installed, you may use pecl install couchbase to install the Couchbase PHP SDK.

Installing on Microsoft Windows

When using Microsoft Windows, download one of the pre-built binaries at Archives, matching your environment or at PECL. You also have the option of downloading the source for the SDK and building it directly.

Post Installation - Setting up the php.ini

Once the PHP SDK has been installed, you need to specify that the PHP interpreter should load the Couchbase SDK as an extension. To do this:

Locate the location of your php.ini file. This can be done by php --ini

$ php --ini
Configuration File (php.ini) Path: /usr/local/etc/php/7.0
Loaded Configuration File:         /usr/local/etc/php/7.0/php.ini
Scan for additional .ini files in: /usr/local/etc/php/7.0/conf.d
Additional .ini files parsed:      (none)

Insert the following line in the php.ini file; this should be in the [PHP] section. If you don’t know where that is, simply search for existing commented or uncommented extension= entries in the file.

Linux and Mac OS

extension=couchbase.so

Windows

extension=couchbase.dll

The Couchbase SDK depends on the JSON PHP extension, so make sure that load order is correct. For example, if your distribution has just a single php.ini file, just insert the line after extension=json.so. If your distribution uses a conf.d-style, name the file with the Couchbase SDK ini so that it will be alphabetically ordered after the JSON extension.

Because the extension depends on the C library (libcouchbase), the shared object libcouchbase.so or libcouchbase.dll has to be accessible by the PHP process when loading the extension. On UNIX-like systems no additional steps are necessary, because the libcouchbase package installs shared objects into a common system location. For Windows though, it must be copied into either into a location from the PATH for the PHP executable or into a directory with like executables (like apache2, IIS or php.exe). This is controlled by your PHP distribution’s setup, so see its documentation for further information.

Information on new features, fixes, known issues as well as information on how to install older release versions is in the release notes.

Hello Couchbase

The Hello Couchbase example consists of one PHP file, hello-couchbase.php. The code opens a connection to Couchbase Server, retrieves a document, modifies the document, and stores the updated document in the database. Here’s the hello-couchbase.php code:

FASTPATH: Couchbase Server 5.0 introduces Role-Based Access Control (RBAC), whereby bucket-access requires authentication by means of username and, typically, password. To access Couchbase Server 5.0-based clusters, you can continue using your existing SDK-version. Alternatively, you can upgrade to the most recent SDK-version, which provides an optimized authentication interface, for use with RBAC. See Authentication, for information.

hello-couchbase.php

<?php
// Connect to Couchbase Server

$cluster = new CouchbaseCluster("couchbase://127.0.0.1");
$bucket = $cluster->openBucket("default");

// Store a document
echo "Storing u:king_arthur\n";
$result = $bucket->upsert('u:king_arthur', array(
    "email" => "kingarthur@couchbase.com",
    "interests" => array("African Swallows")
));

var_dump($result);

// Retrieve a document
echo "Getting back u:king_arthur\n";
$result = $bucket->get("u:king_arthur");
var_dump($result->value);

// Replace a document
echo "Replacing u:king_arthur\n";
$doc = $result->value;
array_push($doc->interests, 'PHP 7');
$bucket->replace("u:king_arthur", $doc);
var_dump($result);

echo "Creating primary index\n";
// Before issuing a N1QL Query, ensure that there is
// is actually a primary index.
try {
    // Do not override default name, fail if it is exists already, and wait for completion
    $bucket->manager()->createN1qlPrimaryIndex('', false, false);
    echo "Primary index has been created\n";
} catch (CouchbaseException $e) {
    printf("Couldn't create index. Maybe it already exists? (code: %d)\n", $e->getCode());
}

// Query with parameters
$query = CouchbaseN1qlQuery::fromString("SELECT * FROM `default` WHERE \$p IN interests");
$query->namedParams(array("p" => "African Swallows"));
echo "Parameterized query:\n";
var_dump($query);
$rows = $bucket->query($query);
echo "Results:\n";
var_dump($rows);

The console output should look similar to this:

Storing u:king_arthur
object(CouchbaseMetaDoc)#4 (4) {
  ["error"]=>
  NULL
  ["value"]=>
  NULL
  ["flags"]=>
  NULL
  ["cas"]=>
  string(9) "mdzlfqp04"
}
Getting back u:king_arthur
object(stdClass)#5 (2) {
  ["email"]=>
  string(24) "kingarthur@couchbase.com"
  ["interests"]=>
  array(1) {
    [0]=>
    string(16) "African Swallows"
  }
}
Replacing u:king_arthur
object(CouchbaseMetaDoc)#6 (4) {
  ["error"]=>
  NULL
  ["value"]=>
  object(stdClass)#5 (2) {
    ["email"]=>
    string(24) "kingarthur@couchbase.com"
    ["interests"]=>
    array(2) {
      [0]=>
      string(16) "African Swallows"
      [1]=>
      string(5) "PHP 7"
    }
  }
  ["flags"]=>
  int(33554438)
  ["cas"]=>
  string(9) "mdzlfqp04"
}
Creating primary index
Primary index has been created
Parameterized query:
object(CouchbaseN1qlQuery)#7 (2) {
  ["options"]=>
  array(1) {
    ["statement"]=>
    string(45) "SELECT * FROM `default` WHERE $p IN interests"
  }
  ["adhoc"]=>
  bool(true)
}
Results:
array(1) {
  [0]=>
  object(stdClass)#9 (1) {
    ["default"]=>
    object(stdClass)#8 (2) {
      ["email"]=>
      string(24) "kingarthur@couchbase.com"
      ["interests"]=>
      array(2) {
        [0]=>
        string(16) "African Swallows"
        [1]=>
        string(5) "PHP 7"
      }
    }
  }
}

API Reference

The API reference is generated for each version. The API reference for version 2.2.3 is at http://docs.couchbase.com/sdk-api/couchbase-php-client-2.2.3