On This Page

Version 2.2.0 - 2.4.1

Couchbase PHP Release Notes and Archives

SDK Installation

Installing on Linux and Mac OS

Before installing the PHP SDK, you must install the C SDK; version 2.8.0 or higher is required for 2.4.1.

After installing the C SDK, install the PHP SDK through your PHP distribution's pecl command:

$ pecl install couchbase

For Mac OS, note that homebrew has a package for the PHP extension and pecl is not installed by default in the most recent versions of homebrew's PHP distribution.  

Installing on Microsoft Windows

When using Microsoft Windows, instead of using PECL, download a pre-built binary matching your environment. You may also download the source for the SDK and build it directly in your environment if you have a complete build toolchain.

Platform x86 x64
PHP 7.1 VC14 NTS php_couchbase-2.4.1-7.1-nts-vc14-x86.zip php_couchbase-2.4.1-7.1-nts-vc14-x64.zip
PHP 7.1 VC14 ZTS php_couchbase-2.4.1-7.1-zts-vc14-x86.zip php_couchbase-2.4.1-7.1-zts-vc14-x64.zip
PHP 7.0 VC14 NTS php_couchbase-2.4.1-7.0-nts-vc14-x86.zip php_couchbase-2.4.1-7.0-nts-vc14-x64.zip
PHP 7.0 VC14 ZTS php_couchbase-2.4.1-7.0-zts-vc14-x86.zip php_couchbase-2.4.1-7.0-zts-vc14-x64.zip
PHP 5.6 VC11 NTS php_couchbase-2.4.1-5.6-nts-vc11-x86.zip php_couchbase-2.4.1-5.6-nts-vc11-x64.zip
PHP 5.6 VC11 ZTS php_couchbase-2.4.1-5.6-zts-vc11-x86.zip php_couchbase-2.4.1-5.6-zts-vc11-x64.zip

Since release 2.3.3, by default binaries for Windows do not require php_igbinary.dll to be installed. If you still need it as Couchbase serializer, you can rebuild binaries from source, or use the following binaries

Platform x86 x64
PHP 7.1 VC14 NTS php_couchbase-2.4.1-7.1-nts-vc14-x86-igbinary.zip php_couchbase-2.4.1-7.1-nts-vc14-x64-igbinary.zip
PHP 7.1 VC14 ZTS php_couchbase-2.4.1-7.1-zts-vc14-x86-igbinary.zip php_couchbase-2.4.1-7.1-zts-vc14-x64-igbinary.zip
PHP 7.0 VC14 NTS php_couchbase-2.4.1-7.0-nts-vc14-x86-igbinary.zip php_couchbase-2.4.1-7.0-nts-vc14-x64-igbinary.zip
PHP 7.0 VC14 ZTS php_couchbase-2.4.1-7.0-zts-vc14-x86-igbinary.zip php_couchbase-2.4.1-7.0-zts-vc14-x64-igbinary.zip
PHP 5.6 VC11 NTS php_couchbase-2.4.1-5.6-nts-vc11-x86-igbinary.zip php_couchbase-2.4.1-5.6-nts-vc11-x64-igbinary.zip
PHP 5.6 VC11 ZTS php_couchbase-2.4.1-5.6-zts-vc11-x86-igbinary.zip php_couchbase-2.4.1-5.6-zts-vc11-x64-igbinary.zip

Post Installation for All Platforms

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:

  1. Locate your php.ini file. This can be done using the command 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)
  2. Insert a line in the php.ini file specifying the extension to be loaded; 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.  Note that the line differs for Linux/Mac OS from Microsoft Windows.
    extension=couchbase.so
    extension=couchbase.dll

Note on Extension Dependencies

If the igbinary extension is available at the time the Couchbase PHP extension is built, it will be built with support for igbinary serialization.  If that extension is not available at build time, later when loading the extension you may see a warning:

[cb,WARN] (pcbc/ext L:383) igbinary serializer is not found

This warning is safe to ignore if you are not planning to use igbinary serialization in your application.

Version 2.4.1 (5 October 2017)

This release contains internal improvements, as well as new features. Note, that minimum version of libcouchbase required is 2.8.0.

New Features

  • PCBC-493: Implement subdocument GET_COUNT API via \Couchbase\Bucket#getCount().
  • Allow to override default pool connection idle interval with couchbase.pool.max_idle_time_sec INI setting.

Changes

  • Ability to run full test suite against CouchbaseMock.
  • Update AnalyticsQuery API: removed experimental hostname() method as it derived from cluster config now.

Version 2.4.0 (5 September 2017)

This release contains internal improvements, as well as new features. Note, that minimum version of libcouchbase required is 2.8.0. Also from this version we drop support of PHP runtime older than 5.6.

New Features

  • PCBC-505: Enable error maps. This feature allows the server to control how the clients handle error codes, for example automatic retrying.
  • PCBC-499: Expose more query options on N1QL query for advanced tuning query performance. See documentation for methods scanCap, pipelineBatch, pipelineCap, maxParallelism, and readonly on \Couchbase\N1qlQuery class.
  • PCBC-485: Expose enhanced error messages. The server might fill new properties of the error (\Couchbase\Exception class instance): "context" (additional text description of the error) and "ref" (reference id in the server logs).

Improvements

  • More examples: XATTRs and RBAC user management.

Version 2.3.4 (19 July 2017)

This release contains internal improvements, as well as new features. Note, that minimum version of libcouchbase required is 2.7.6.

New Features

  • PCBC-495: Update user management APIs: added method to fetch user by name, and support for authentication domains.

Improvements

  • PCBC-478: Add tests for Error Map using CouchbaseMock

Version 2.3.3 (31 May 2017)

This release contains internal improvements, as well as new features. Note, that minimum version of libcouchbase required is 2.7.5.

New Features

  • PCBC-475: Add support for term range query and geo search queries in full text search.
  • PCBC-468: Add support for user CRUD in ClusterManager (RBAC feature of upcoming Couchbase Server 5). Read more about it in the server documentation.
  • PCBC-489: Add shortcut for PasswordAuthenticator as Cluster->authenticateAs($username, $password).
  • PCBC-472: Expose setting accessor for configuration polling interval. Accessible as Bucket->configPollInterval. With Couchbase Server 5 it will allow faster failover.

Fixed Issues

  • PCBC-487: \Couchbase\N1qlQuery->adhoc() method actually worked in reversed way. When this parameter set to true (which is default), the library creates prepared statement, and skip it otherwise.
  • PCBC-494: Fix double free error in passthruEncoder.

Version 2.3.2 (2 May 2017)

This release contains internal improvements, as well as new features. Note, that minimum version of libcouchbase required is 2.7.4.

Known Issues

  • PCBC-487: \Couchbase\N1qlQuery->adhoc() method actually worked in reversed way. When this parameter set to true (which is default), the library creates prepared statement, and skip it otherwise. Releases after 2.3.3 will fix this behaviour and really use adhoc queries by default.

New Features

  • PCBC-451: Add RBAC support in \Couchbase\PasswordAuthenticator class (Couchbase Server 5.x feature). Read more about it in the blog Authentication and Authorization with RBAC.
    $authenticator = new \Couchbase\PasswordAuthenticator(;
    $authenticator->username('john')->password('s3cret');
    
    $cluster = new \Couchbase\Cluster('couchbase://127.0.0.1');
    $cluster->authenticate($authenticator);
    
  • PCBC-440: Add experimental support of extended attributes for subdocument operations. This might be useful for storing application-specific information, which should not be treated as document contents.
    $b->upsert('doc1', ['foo' => 'bar']);
    
    $b->mutateIn('doc1')
        ->upsert('app.created_by', ['name' => 'John Doe', 'role' => 'DB administrator'],
                ['xattr' => true, 'createPath' => true])
        ->execute();
    
    $result = $b->lookupIn('doc1')
        ->get('app.created_by', ['xattr' => true, 'createPath' => true])
        ->execute();
    $result->value[0]['value'];
    // ['name' => 'John Doe', 'role' => 'DB administrator']
    
  • PCBC-453: Verify that ClusterManager supports ephemeral buckets. This is new type of buckets accessible in Couchbase Server 5, which basically enhanced Memcached-style bucket with replication, failover and other Couchbase bucket features.
    $cluster = new \Couchbase\Cluster('couchbase://127.0.0.1');
    $cluster->manager()->createBucket('ephemeralTest', ['bucketType' => 'ephemeral']);
    

Fixed Issues

  • PCBC-473: Fix incorrect bucket reference copy in subdocument mutation/lookup builders, which might lead to segfault.
  • PCBC-474: Fix segfault when using ViewQuery::keys().
  • PCBC-476: Do not call destructors on unintialized ZVALs. Fixes possible segfaults with view queries on PHP 5.x.
  • PCBC-477: Lookup JsonSerializable interface in run time, instead of compile time using php_json_serializable_ce symbol. This fixes support of some 5.4-5.5 builds.
  • PCBC-479: Do not allow to create objects in invalid state. For example Cluster might return an instance, and only show PHP warning on invalid arguments.
  • PCBC-481: Fix Bucket->counter() without specifying delta value results in null pointer dereference.
  • PCBC-482: mapSize/setExists/setRemove methods of Bucket did not check if 'get' sub-request had thrown exception. This cause segfault, if operation executed on keys which do not exist.

Version 2.3.1 (5 April 2017)

This release contains internal improvements, as well as new features. Note, that minimum version of libcouchbase required is 2.7.3.

Fixed Issues

  • PCBC-459: Restore \Couchbase\Bucket::unlock() method, which has been lost in refactoring.
  • PCBC-460: Prefer managed strings to persistent when storing document values.
  • PCBC-461: Deallocate intermediate results when using encoder compression
  • PCBC-462: Replace new lines in log entries with space.
  • PCBC-464: Fix NumericRangeFacet with NULL boundary on PHP 5.4.
  • PCBC-463: Fix incorrect reference counting on Search API. (might lead to segfaults and leaks).
  • PCBC-465: Check encoded ViewQuery before sending to libcouchbase.
  • PCBC-467: Intermediate values in Datastructures API might leak. (e.g. result of internal "get" to find out size of the list).
  • PCBC-471: Fixed issue, when the library always use credentials for the first bucket in Authenticator.

New features

  • PCBC-469: Implement SearchQuery->sort() function to support sorting FTS results, which is accessible in Couchbase Server 4.6+.
  • PCBC-441: Add experimental support of Analytics query. Read more about Analytics Service at documentation site

Version 2.3.0 (7 March 2017)

This release contains internal improvements, as well as new features. Note, that minimum version of libcouchbase required is 2.7.2. This release does not depend on the PCS extension. All classes which were previously written in PHP are now implemented in the Zend C APIs. This means they do not require extra evaluation on module load or request initialization.

New features

Fixed Issues

  • PCBC-443: PCS dependency has been removed and all classes were rewritten using the Zend C API

Breaking change

With previous default the options were defined in the global variables $COUCHBASE_DEFAULT_ENCOPTS and $COUCHBASE_DEFAULT_DECOPTS.  Starting with 2.3 if you are adjusting those defaults, this should now be done through INI variables couchbase.encoder.* and couchbase.decoder.*. The full list of the supported INI options with detailed description is in the API documentation.

Version 2.2.4 (26 December 2016)

This release contains bug fixes and performance improvements. Note, the minimum version of libcouchbase required is 2.6.1. This release depends on PCS extension.

Known Issues

  • PCBC-443: Installation issues with PCS Extension.  Partially owing to a bug in PCS and partially owing to adding an additional dependency, the PCS Extension has been problemmatic.  It will be removed in a future release.  If this impacts your installation, use the 2.2.3 release.

Fixed Issues

  • PCBC-401: Embed PHP classes using PCS (PHP Code Service) extension 1.3.1. This fixes a performance issue, where the extension would spend time during each request to evaluate and load Couchbase classes written in PHP. The pecl/pcs extension has to be installed and loaded before loading couchbase SDK.
  • PCBC-439: Fix code which handles document compression flags, so a compressed document is not handled by a JSON decoder.
  • PCBC-438: Fix CouchbaseBucket#getFromReplica(), which returned NULL for all requests.

Version 2.2.3 (4 October 2016)

This release contains bug fixes and transcoder improvements. Note, the minimum version of libcouchbase required is 2.6.1.

New Features and Behavioral Changes

  • PCBC-389: Deserialize legacy documents (e.g. documents included in sample buckets) as JSON with falling back to old behaviour.

Fixed Issues

  • PCBC-428: Raise InvalidArgumentException when credentials missing for CouchbaseClusterManager instead reporting fatal error.

Version 2.2.2 (6 September 2016)

This release contains documentation updates and observability improvements. Note, the minimum version of libcouchbase required is 2.6.1.

New Features and Behavioral Changes

  • PCBC-410: Consolidate libcouchbase and extension loggers and expose them through the PHP built-in logger. Read more about using this feature at Collecting Information section of SDK guide.
  • PCBC-417: Do not send duplicated keys in multi-get and multi-remove operations.

Fixed Issues

  • PCBC-409: Propagate errors during View creation. Now, broken view definitions will cause CouchbaseException with message set to error explanation.
  • PCBC-423: Report failed N1QL queries in log output.

Version 2.2.1 (8 August 2016)

This release contains documentation updates and bug fixes for features introduced over the 2.2 beta development cycle. Note, the minimum version of libcouchbase required is 2.6.1.

New Features and Behavioral Changes

  • PCBC-414: All CouchbaseN1qlQuery methods return $this to allow method chaining.

Fixed Issues

  • PCBC-416: Fix segfault on multi-get for duplicated keys.

Version 2.2.0 (6 July 2016)

This release contains documentation updates and bug fixes for features introduced over the 2.2 beta development cycle. Note, the minimum version of libcouchbase required is 2.6.1.

Backward-incompatible API changes since 2.1.0

  1. CouchbaseBucket->query() accepts only 2 arguments, and query properties supposed to be set in query objects (CouchbaseN1qlQuery, CouchbaseViewQuery, CouchbaseSearchQuery instances).
    For 2.1.0:
    $query = CouchbaseN1qlQuery::fromString("SELECT * FROM `travel-sample` WHERE city=$arg");
    $bucket->query($query, array("arg" => "London"), true);
    For 2.2.0:
    $query = CouchbaseN1qlQuery::fromString("SELECT * FROM `travel-sample` WHERE city=$arg");
    $query->namedParams(array("arg" => "London"));
    $bucket->query($query, true);
  2. Return value of CouchbaseBucket->query() is always object, but the contents of the rows attribute still controlled by second argument to the method.
    For 2.1.0:
    $query = CouchbaseN1qlQuery::fromString("SELECT * FROM `default` LIMIT 10");
    // Rows as nested arrays
    $res = $bucket->query($query, NULL, true);
    foreach ($res as $row) {
        printf("%s\n", $row['default']['myprop']);
    }
    // Rows as objects
    $res = $bucket->query($query, NULL, false);
    foreach ($res as $row) {
        printf("%s\n", $row->default->myprop);
    }
    For 2.2.0
    // Rows as nested arrays
    $res = $bucket->query($query, true);
    foreach ($res->rows as $row) {
        printf("%s\n", $row['default']['myprop']);
    }
    // Rows as objects
    $res = $bucket->query($query, false);
    foreach ($res->rows as $row) {
        printf("%s\n", $row->default->myprop);
    }
    This is done to allow inject additional meta information into result, and to have a way to extend result objects in the future. For example, this is how one can pull N1QL metrics from results:
    $res = $bucket->query($query);
    printf("Query has been completed in %s and returned %d rows\n",
           $res->metrics['elapsedTime'], $res->metrics['resultCount']);
    //=> Query has been completed in 8.543433ms and returned 1 rows

New Features and Behavioral Changes

  • PCBC-393: Support for enhanced durability.
  • PCBC-382: Cluster level authentication.
  • Expose meta for N1QL and Search Query responses.

Fixed Issues

  • PCBC-398: Expose methods for parameterized N1QL queries.

Version 2.2.0 Beta 4 (29 June 2016)

New Features and Behavioral Changes

  • PCBC-380: Support for AT_PLUS consistency.
  • PCBC-381: Support for Full Text Search queries.
  • PCBC-395: Type checks incorrectly for booleans.  This could lead to a CouchbaseException occurring when query results contain numbers instead of booleans.

Version 2.2.0 Beta 3 (25 May 2016)

New Features and Behavioral Changes

Fixed Issues

  • PCBC-395: Type checks incorrectly for booleans.  This could lead to a CouchbaseException occurring when query results contain numbers instead of booleans.

Version 2.2.0 Beta 1 and 2 (19 April 2016)

Owing to a package metadata problem, Beta 1 of the PHP client was immediately superseded by Beta 2.  

New Features and Behavioral Changes

Fixed Issues

  • PCBC-376: Calling extension from within from transcoder fails.
  • PCBC-373: Encoding of plus sign fails for view query ranges.