PHP Client Library

Couchbase Server for PHP Development

The PHP client library provides fast access to documents in Couchbase Server 2.0. With JSON documents and Couchbase server 2.0 you have new ways to index and query data stored in the cluster through views. These view(s) can be accessed using the newly defined View object.

You can provide different perspsectives to the data. For example, on the sample beer data, you can sort by category, ABV and so on depending on your taste!

Step 0: Get a Server

Get, Install, and Start Couchbase Server. Come back here when you're done.

Step 1: Get a Client Library

Step 1.0: Get libcouchbase

Since the PHP extension builds on the 2.0 version of the Couchbase C SDK you will need to get it. The C SDK downloads and instructions are here.  Be sure to install the header files, which are frequently in a -dev or -devel package, depending on your Operating System.

Note if you have an earlier version of the Couchbase C SDK, remove it before you install the new C SDK.

Step 1.1: Install the PHP SDK

Installing with Pear

To install with Pear, do the following steps:

  1. Install the C Library like before.
  2. Install Pear with # sudo apt-get install php-pear.
  3. Install build-essential (.make ..etc) with # sudo apt-get install build-essential.
  4. Install Couchbase SDK with # sudo pecl install couchbase.
  5. Update php.ini with extension=couchbase.so.
  6. Restart Apache # sudo service apache2 restart.
Installing on Linux or Mac OS X

Get the PHP SDK for your platform. The PHP SDK is distributed as a PECL archive, which can be installed from the pecl command installed along with your PHP installation. 

To install directly from the official PECL repository on Linux, Mac OS X or any other UNIX like system, simply:

shell> sudo pecl install couchbase

The extension can also be built from a downloadable source archive, though installation from PECL is the recommended approach.

Assuming all dependencies are met, the extension will build and automatically be installed.

Installing the Beta Extension on Windows

To install one of the beta extensions on Windows, simply unzip the archive and move the included .dll files to your PHP extension directory.

You can download the Windows DLLs directly from the PECL for Windows site.

Step 1.2: Update your PHP Configuration

You will add the couchbase.so extension to your php.ini file. To find where your php.ini file is, try php -i | grep "Configuration File" or look at your <?php phpinfo() ?> output. Edit your php.ini to include a line similar to this one:

 extension=couchbase.so

Do note that on some releases or in some configurations of PHP, you may need to provide the full path to the extension object.

To find extension_dir, try:

shell> php -i | grep extension_dir ~
extension_dir => /usr/lib/php/extensions/no-debug-non-zts-20090626 => /usr/lib/php/extensions/no-debug-non-zts-20090626

Note: With the PHP packages on Red Hat/CentOS distributions, the PHP included JSON encoding is not automatically available to other libraries, including Couchbase PHP SDK. To make the JSON library available to Couchbase PHP SDK, add these two lines to php.ini, in this order:

extension=json.so
extension=couchbase.so

If the extension is already loaded for some other reason, you may receive a warning. This can happen on some systems where PHP may be configured to initialize differently for the CLI versus running as an extension on a web server. If you receive a warning about JSON encoding and decoding already being available, it can be safely ignored.

Step 2: Try it out!

Create this PHP script. It gets you started  performing reads/writes to the server from the PHP SDK:

<?php
// adjust these parameters to match your installation
$cb = new Couchbase("127.0.0.1:8091", "", "", "default");
$cb->set("a", 101);
var_dump($cb->get("a"));
?>

The line with new Couchbase() establishes a connection to Couchbase Server with hostname:port, username, password and bucket name in that order. The username and bucket name are most typically the same, but an empty string is used in the case of the default bucket, as it does not use authentication. Next, we set the key "a" to 101. Finally, we get the value for our key "a" and output it. When you run this script it outputs int(101).

Indexing and Querying with Views

The Couchbase PHP SDK 1.1 has support for for views, which you use to index and find documents stored in the server. Couchbase Server 2.0 includes a beer-sample database to try out this feature.

First, set up the beer-sample database if you did not do so at installation time.

  1. In the Couchbase Web Console, click on the Views tab.
  2. Select on beer-sample in the drop down to choose this database.
  3. Click Create Development View to create a new function.
  4. Name the Design Document _design/dev_beer and the View Name beer_by_name.
  5. Click Edit to add your function and then Save it:
function (doc, meta) {
  if (doc.type == "beer") {
    emit(doc.name);
  }
}
  1. You can click Show Results to see sample results based on the new function.

Now you are ready to actually query the view and get results from the PHP SDK.

Querying from the PHP SDK

With the new view function set up to work with data from the beer-sample database using Couchbase Web Console, you can query it from the PHP SDK:

<?php
$cb = new Couchbase("127.0.0.1:8091", "beer-sample", "", "beer-sample");
$result = $cb->view("dev_beer", "beer_by_name");
foreach($result["rows"] as $row) {
  echo $row['key'] . "\n";
}

The view() method from the PHP SDK queries the server for the function we defined earlier in Couchbase Web Console. The server returns a result set that you can iterate over to output each item. This will output results from the query similar to the example below:

1084 Barleywine
8-Ball Stout
Alaskan Summer Ale

The Couchbase Server 2.0 install includes a few more sample functions you can query from the PHP SDK. For example to retrieve all beers which begin with O and end prior to R, you can provide additional parameters as part of your query:

$result = $cb->view('dev_beer', 'beer_by_name', array('startkey' => 'O', 'endkey' => 'R'));

Here we want to query for results that begin with the letter O and end prior to the letter R and get results similar to those below:

Oak Stout
....
Pumpkin Ale

Congratulations, you have already learned some of the basic build blocks used with the PHP SDK for Couchbase Server 2.0. To find out more about developing with Couchbase SDKs and working with views, see Couchbase Developer Guide 2.0 and Finding Data with Views.

To Learn More:

If you are ready to learn more, the Getting Started Guide for PHP is a good place to continue. From there you can go through the tutorial which demonstrates more functionality from the SDK.

If you have any questions, problems or suggestions, please let us know on the Couchbase SDK forums.