A newer version of this documentation is available.

View Latest

Hello Couchbase Example

The first code example is a "Hello Couchbase" app.

The example "Hello Couchbase" works with the beer-sample bucket that is provided with Couchbase Server. The following sections contain instructions for running the example app and the annotated Hello Couchbase code.

Running Hello Couchbase

To run the example Hello Couchbase program:

  1. Start Couchbase Server on your computer.

  2. Open the Couchbase administrator console.

  3. Make sure the beer-sample bucket is available by checking for it under the Data Buckets tab. If you need to install the bucket:

    1. Select Settings  Sample Buckets.

    2. Install the beer-sample bucket.

  4. If you haven’t already installed the Couchbase PHP extension, install the PHP SDK.

  5. Copy and paste the Hello Couchbase code into a file named hello-couchbase.php. The code is located in the next section.

  6. In a terminal window, change to the directory that contains the hello-couchbase.php code.

  7. Execute the following command:

    $ php hello-couchbase.php

Hello Couchbase code

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:

hello-couchbase.php
<?php
// Connect to Couchbase Server

$cluster = new CouchbaseCluster('http://127.0.0.1:8091');
$bucket = $cluster->openBucket('beer-sample');

// Retrieve a document

$result = $bucket->get('aass_brewery-juleol');
$doc = $result->value;

echo $doc->name . ', ABV: ' . $doc->abv . "\n";

// Store a document

$doc->comment = 'Random beer from Norway';

$result = $bucket->replace('aass_brewery-juleol', $doc);

var_dump($result);

The console output should look similar to this:

Juleøl, ABV: 5.9
object(CouchbaseMetaDoc)#6 (4) {
  ["error"]=>
  NULL
  ["cas"]=>
  resourceFix (5) of type (CAS)
}

The following points explain each step in the example:

  • Connecting

    A Bucket object represents a connection to a single bucket within the cluster.

    A bucket represents a logical namespace for a key. All keys must be unique within a single bucket, but multiple buckets can have keys with the same names and they will not conflict. A new connection object must be created for each bucket that you want to interact with in your application. This example creates one connection to the beer-sample bucket.

    The constructor is passed the bucket name, which is beer-sample, and a node on the cluster to connect to. You can pass any node that is a member of the cluster. This example uses the local cluster instance.

  • Retrieving Data

    The get() method initiates an asynchronous request to retrieve the specified key. If the key exists, the callback is invoked with a results object that contains the value of the key and any additional metadata returned from the cluster. To get the actual value of the object, you can access the result object’s value property.

    If the key does not exist on the server, the callback is invoked with an unset value property on the result object (it will not set the callbacks error parameter).

  • Storing Data

    To store documents in the server, you can use one of the set family of methods. This example uses the replace() method, which enforces the constraint that a previous value of the document must already exist. This can be thought of as an update operation in terms of CRUD (create, read, update, delete) operations.

    The storage methods also return a result object that contains metadata about the value that was stored.