A newer version of this documentation is available.

View Latest

Couchbase PHP Release Notes and Archives

      Release notes, installation instructions, and download archive for the Couchbase PHP Client.

      These pages cover the 3.x versions of the Couchbase PHP SDK. For release notes, download links, and installation methods for 2.6 and earlier releases of the Couchbase PHP Client, please see the 2.x PHP Release Notes & Download Archive.

      SDK Installation

      Installing on Mac and Linux systems

      Before installing the PHP SDK, you must install the C SDK — libcouchbase (LCB); version 3.2.0 or higher is required for PHP Client 3.2.

      After installing libcouchbase, install the Couchbase PHP SDK through your PHP distribution’s pecl command:

      $ pecl install couchbase

      Or install from the Couchbase repository:

      $ pecl install https://packages.couchbase.com/clients/php/couchbase-3.2.2.tgz

      Then follow the post-installation steps.

      Alpine Linux

      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.

      Using apk, you would install your preferred php version, install libcouchbase, and then install the equivalent pecl package for the version of php that you’re using.

      $ apk add php7
      $ apk add libcouchbase
      $ apk add php7-pecl-couchbase

      Then follow the post-installation steps.

      Installing on Microsoft Windows

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

      Binaries labeled with (TLS) are linked against OpenSSL 1.1.1d (MSVC15) to support TLS connections to Couchbase. Simply download the correct version according to your installation details and then copy the corresponding libcouchbase.dll and php_couchbase.dll binaries into the extension_dir as configured in your php.ini configuration.

      Depending on your installation details, you may also have to add the extension_dir to your PATH variable.

      The packages do not include OpenSSL binaries, therefore they have to be installed in the PATH (see https://wiki.openssl.org/index.php/Binaries) for your Windows PHP distribution.

      $ copy /b libcouchbase.dll C:\php\ext
      $ copy /b php_couchbase.dll C:\php\ext






      PHP 7.4 VC15 NTS


      PHP 7.4 VC15 ZTS


      PHP 8.0 VC16 NTS


      PHP 8.0 VC16 ZTS


      PHP 8.1 VC16 NTS


      PHP 8.1 VC16 ZTS


      PHP 7.4 VC15 NTS (TLS)


      PHP 7.4 VC15 ZTS (TLS)


      PHP 8.0 VC16 NTS (TLS)


      PHP 8.0 VC16 ZTS (TLS)


      PHP 8.1 VC16 NTS (TLS)


      PHP 8.1 VC16 ZTS (TLS)


      Then follow the post-installation steps.

      Post Installation for All Platforms

      Once the PHP SDK has been installed, you need to specify that the PHP interpreter should load the Couchbase PHP 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.4
        Loaded Configuration File:         /usr/local/etc/php/7.4/php.ini
        Scan for additional .ini files in: /usr/local/etc/php/7.4/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.

        extension=json      ; not needed with PHP 8.0.0+
        on PHP version 7.2.0 and up, simply using the extension name is preferred. Previously, you might have used couchbase.so or couchbase.dll, depending on your platform.

      PHP Composer

      Once the PHP extension is installed, it may be used as any other PHP library through composer as posted at packagist.org. To add it to your project’s dependency list, use the following composer command:

      $ composer require couchbase/couchbase

      Note on Extension Dependencies

      The Couchbase SDK depends on the JSON extension, which must be loaded before the SDK. However, it is already included on PHP 8.0.0+ as a core extension.

      Version 3.2.2 (8 December 2021)

      Version 3.2.2 is the third release of the 3.2 series, bringing new features and fixes. This is the first release that supports PHP 8.1.

      • PCBC-799: Implemented Collection#getMulti, Collection#upsertMulti, and Collection#removeMulti to perform operations in batches.

      • PCBC-788: PHP SDK now handles error codes for rate and quota limit conditions generated by the server.

      • PCBC-796: Added storage backend option for bucket manager.

      • Updated jsonSerialize methods to stop showing deprecation errors in PHP 8.1.

      Version 3.2.1 (14 October 2021)

      Version 3.2.1 is the second release of the 3.2 series, bringing new fixes.

      • PCBC-770: Fixed memory leak while decoding subdoc JSON.

      • PCBC-782: Updated minimal requirement for libcouchbase to 3.2.2.

      • Other memory fixes and improvements.

      Version 3.2.0 (26 July 2021)

      Version 3.2.0 is the first release of the 3.2 series, bringing new features and fixes.

      • PCBC-750: Deprecate getScope in collections manager, in favour of getAllScopes.

      • PCBC-725: Add support for collections to Full Text Search.

      • PCBC-764: Fix parsing error using BooleanSearchQuery→mustNot Query by correcting serialization.

      • PCBC-709: Add Scope level Analytics Queries.

      • PCBC-732: Expose Partition Information in Query Management API.

      • PCBC-773: Add Analytics Index Manager.

      • PCBC-769: Do not allow CAS option with Increment/Decrement counter operations, which are always atomic.

      • PCBC-767: Fix error creating Scopes/Collections by constructing URL correctly.

      • PCBC-738: Enable document updates without resetting Expiry time by adding preserveExpiry support for mutations (replace, upsert and mutateIn).

      • PCBC-700: Manage Remote Links for Analytics service.

      • PCBC-706: Provide Tracing interface.

      • PCBC-743: Provide Metrics interface using OpenTelemetry.

      Version 3.1.2 (13 May 2021)

      Version 3.1.2 is the third release of the 3.1 series, bringing stabilizations and enhancements over 3.1.0.

      • PCBC-761: Fixed return interface for expiryTime methods.

      • PCBC-760: Exposed error messages in Query exceptions.

      • PCBC-759: Take into account decoder.json_arrays INI setting when decoding Query rows.

      • PCBC-758: The SDK will now raise an exception if invalid CAS is passed to unlock.

      • PCBC-729: Updated URLs for Collections management API.

      Version 3.1.1 (4 March 2021)

      Version 3.1.1 is the second release of the 3.1 series, bringing stabilizations and enhancements over 3.1.0.

      • PCBC-745: Throw BadInputException when string cannot be used as CAS in mutation operations.

      • PCBC-746: Added tests for transcoding empty value.

      • PCBC-748: Fixed return value of expiry() methods for ReplaceOptions, IncrementOptions, DecrementOptions, and MutateInOptions in the documentation stubs.

      Version 3.1.0 (20 January 2021)

      Version 3.1.0 is the first GA release of the 3.1 series, bringing stabilizations and enhancements over 3.0.10 and the 3.0 SDK, and adding features to support Couchbase Server 6.6 and 7.0β.

      Behavioral Change

      Previously, when the application stored an instance of a string which is encoded as a JSON value, SDK 3.0.x would decode it as a JSON and return an object/array. In 3.1.0 the issue has been fixed, and now the application will receive the instance of the string as expected.

      • PCBC-599: Implemented Datastructures in PHP library (available via composer):

        • CouchbaseList,

        • CouchbaseMap,

        • CouchbaseQueue,

        • CouchbaseSet.

      • PCBC-742: Propagate custom value transcoder to results.

      • PCBC-707: Added scope-level query and scope qualifier support for QueryOptions.

      • PCBC-741: Fixed memory leak in Bucket::viewQuery().

      • PCBC-734: Fixed destruction of SearchOptions.

      • PCBC-591: Updated error handling howto documentation.

      Version 3.0.5 (6 December 2020)

      • PCBC-699: Added support for minimal durability settings for bucket manager.

      • PCBC-718: Deprecated expiry() on GetResult and LookupInResult. expiry() is deprecated in favour of expiryTime() which returns DateTimeInterface.

      • PCBC-715: Refactored document expiry duration:

        • Allowing one to specify DateTimeInterface objects as expiry value in mutation options;

        • When expiration is set as long in seconds, treat the value as relative if it is less than 50 years in seconds. In this case take the current time and add to the expiration value.

      • PCBC-733: Added missing fields for SearchFacet results

      • PCBC-720: Added option to disable search scoring.

      • Support PHP 8. Dropped support for PHP older than 7.2.

      Version 3.0.4 (11 November 2020)

      Version 3.0.4 is the fifth release of the 3.0 series, bringing enhancements and bugfixes over the last stable release.

      • PCBC-722: Fixed boolean Search query encoding.

      • PCBC-703: Added support for Query with FlexIndex (FTS).

      • PCBC-719: Enhanced user management for Collections.

      • PCBC-702: Implemented geopolygon Search query.

      • PCBC-705: Updated eviction policy types. It now covers ephemeral buckets.

      • PCBC-721: Allow to fall back to bucket connection for older Server releases.

      Version 3.0.3 (17 June 2020)

      Version 3.0.3 is the fourth release of the 3.0 series, bringing enhancements and bugfixes over the last stable release.

      • PCBC-696: Fixed encoding issue in QueryString search query.

      • PCBC-667: Added maxExpiry for CollectionSpec of collection manager.

      • PCBC-690: Increased refcount of arg in ViewOptions::keys().

      • PCBC-688: Temporary strings are now copied in ViewOptions builder.

      • PCBC-666: Fixed invalid memory access of Query result "meta".

      • PCBC-665: Fixed build issue on Debian.

      • Documentation improvements:

        • PCBC-683: update documentation steps

        • PCBC-675: Add API docs for exceptions

        • Update API ref to add docs for results objects

        • Update API reference for remaining undocument query API

        • PCBC-672: Add API docs for KV functions

        • PCBC-671: Add API reference docs for cluster/bucket etc.

        • PCBC-694: Remove \ namespace prefix in return type and argument definitions

        • PCBC-694: Allow null to be passed to nullable options

        • PCBC-693: replace GetAllReplicaOptions with GetAllReplicasOptions

        • PCBC-692: Use MutationResult instead of StoreResult

        • PCBC-691: Use "|null" instead of "?" in phpdoc.

      Version 3.0.2 (4 March 2020)

      Version 3.0.2 is the third release of the 3.0 series, bringing enhancements and bugfixes over the last stable release.

      • PCBC-660: Fixed detection of replace with CAS, so CasMismatchException now raised where necessary instead of KeyExistsException.

      • PCBC-663: Search method now increases refcounter of search object, avoiding double-free error in the script termination handler.

      • Fixed memory leaks.

      • Fixed manifest issue leading to install failure.

      Version 3.0.1 (4 February 2020)

      Version 3.0.1 is the second release of the 3.0 series, bringing enhancements and bugfixes over the last stable release.

      • Exposed manager APIs on Cluster level:

        • Cluster#queryIndexes() → QueryIndexManager

        • Cluster#searchIndexes() → SearchIndexManager

        • Cluster#users() → UserManager

        • Cluster#buckets() → BucketManager

      • Exposed manager APIs on Bucket level:

        • Bucket#collections() → CollectionManager

        • Bucket#viewIndexes() → ViewIndexManager

      Version 3.0.0 (21 January 2020)

      This is the first GA release of the third generation PHP SDK.


      Numerous Alpha and Beta releases were made in the run-up to the 3.0 release, and although unsupported, the release notes and download links are retained for archive purposes here.

      Older Releases

      Although no longer supported, documentation for older releases continues to be available in our docs archive.