Repository navigation
API Reference: https://docs.couchbase.com/sdk-api/couchbase-php-client-4.6.0
Full Changelog: 4.5.0...4.6.0
Packagist: https://packagist.org/packages/couchbase/couchbase#4.6.0
composer require ext-couchbase:4.6.0
composer require couchbase/couchbase:4.6.0
composer require couchbase/couchbase-opentelemetry:4.6.0The C++ core moves from 1.3.1 to 1.5.1. Changes that the core brings are listed with their CXXCBC ticket.
Behaviour Changes
-
PCBC-1088: One extension module -- Release archives carry one module,
couchbase, incouchbase.soorphp_couchbase.dll. The-abiarchives are no longer produced (#266).- An INI file that loads
couchbase_X_Y_Zhas to change toextension=couchbase. - The extension's functions live in
Couchbase\Extensionand its exceptions inCouchbase\Exception. The versionedCouchbase\Extension_X_Y_Znamespaces,ExtensionNamespaceResolverand theCOUCHBASE_EXTENSION_NAMESPACEconstant are removed, and so is thecouchbase_extension_abirow ofphpinfo(). - The library checks only that the
couchbasemodule is loaded. It does not detect an extension from another release. The Composer package has to be pinned to the installed extension's release. - Loading two SDK versions in one PHP process is not supported. Running each application in its own container is recommended; CONTAINERS.md explains why and shows how to install a release archive into an official PHP image.
- An INI file that loads
-
Minimum PHP version -- PHP 8.2 is the minimum supported version. PECL refuses to install 4.6.0 on PHP 8.1.
-
Interface methods --
ClusterInterfacegainsdisconnect()andCollectionInterfacegainsgetReplica(). Classes that implement these interfaces have to add them. -
PCBC-1056: Connection cache key -- Clusters share a cached connection only when their connection strings and all options exported by
ClusterOptions::export()are equal (#267).- The key covered only the connection string, the authenticator, and the core tracing, core metrics and span buffering flags. A second cluster that differed in a timeout, TLS verification, network or DNS-SRV option received the first cluster's connection. It then ran with the first cluster's options.
-
PCBC-1057: Persistent connection limits --
couchbase.max_persistentapplies when a connection is created (#268).- A connection opened at the limit frees idle connections until it fits. Detached connections go first, then cached ones, least recently used first. When every connection is in use, the new one is kept over the limit.
- After each request, a cached connection is freed only when it has been idle longer than a non-negative
couchbase.persistent_timeout. With-1, connections are no longer freed after each request. phpinfo()reports the number of persistent connections ascouchbase_persistent_connections.
-
CXXCBC-838: TLS hostname verification -- TLS connections check that the server certificate's SAN or CN matches the hostname, and send SNI. A certificate without a matching name fails the handshake.
-
PCBC-1087, CXXCBC-882: Query error 2120 -- A query that the server rejects with error 2120 (
E_ADMIN_AUTH) raisesAuthenticationFailureException, notInternalServerFailureException(#265). -
CXXCBC-1049: HTTP 400 -- An unrecognised HTTP 400 from a service raises
InvalidArgumentException. -
CXXCBC-1059: Dropped query index -- Dropping a query index that does not exist raises
IndexNotFoundException.
New Features and Enhancements
-
PCBC-1074, PCBC-1085: Read from a specific replica --
Collection::getReplica()reads a document from one replica (#259, #264).GetReplicaStrategy::fromIndex()selects it withReplicaIndex::FIRST,SECONDorTHIRD.DocumentNotFoundOnReplicaException,ReplicaIndexOutOfBoundsExceptionandReplicaIndexCurrentlyUnavailableExceptionreport the replica-specific failures.- Over
couchbase2://,getReplica()throwsUnsupportedOperationException.
-
PCBC-1070: Search score fusion --
SearchOptions::scoring()selects how hybrid search results are scored (#257).SearchScoringReciprocalRankFusionandSearchScoringRelativeScoreFusionrequire Couchbase Server 8.1 or later, and raiseFeatureNotAvailableExceptionon older servers.SearchScoringNoneworks on any server.
-
PCBC-974: Retry strategy per operation -- Key/value options accept
retryStrategy()withRetryStrategy::BEST_EFFORTorRetryStrategy::FAIL_FAST(#271). Any other value throwsInvalidArgumentException.- With
FAIL_FAST, a mutation on a locked document throwsDocumentLockedExceptionat once.upsertMulti()reports that exception for the locked item. - The option applies to
getMulti(),upsertMulti(),removeMulti()and every single-document operation except the replica reads. - Over
couchbase2://, the same values select the BestEffort and FailFast strategies.
- With
-
PCBC-1058:
Cluster::disconnect()-- Closes the cluster's connection and removes it from the cache (#269).- The next operation throws
CouchbaseExceptioncarryingcluster_closed. This applies to the cluster, to every bucket and collection opened from it, and to every other cluster sharing the connection. - Transactions and range scans obtained before
disconnect()fail withcluster_closed. A cluster created afterwards with the same arguments bootstraps a new connection. - Over
couchbase2://,disconnect()throwsUnsupportedOperationException.
- The next operation throws
Bug Fixes
-
PCBC-1089: Logging in a forked child -- A process forked with
couchbase.log_levelset no longer hangs in module shutdown (#270, fixes #221).- The spdlog flusher thread is stopped before
fork()and started again in the parent and the child. - With
couchbase.log_pathset, a child forked withoutCluster::notifyFork()writes to a log file named after its own pid. It no longer writes to the parent's file. - A child that PHP forks only to
exec()another program (exec(),shell_exec(),proc_open()) opens no log file. - A sink lock held by another thread at
fork()no longer blocks the child's first message.
- The spdlog flusher thread is stopped before
-
PCBC-1057:
Cluster::setAuthenticator()-- The connection moves out of the cache (#268). A cluster connected later with the previous credentials no longer receives it. Detached connections that nothing references are freed after each request. -
PCBC-1057: Thread-safe builds -- Each thread initialises its module globals, so its persistent connection count starts from 0 (#268).
-
PCBC-1083: Numeric range facets --
NumericRangeFacetResult::min()andmax()keep fractional bounds as floats. A range with min-1.5reported-1(#263). -
PCBC-1081: Legacy durability strings -- An unknown
persistToorreplicateTostring raisesInvalidArgumentExceptionnaming the value, and the document is not written (#262). -
View
skipoption -- A view query withViewOptions::skip()no longer throwsInvalidArgumentException(#255). -
32-bit Windows build -- The meter duration is parsed into a
zend_long, which fixes the x86 Windows build (#265). -
PCBC-1071: Meter wrapper build -- The meter wrapper builds against the core's
metric_attributesAPI (#256).
Deprecations
- PCBC-1070:
SearchOptions::disableScoring()is deprecated in favour ofscoring(new SearchScoringNone()).
Known Issues
- CXXCBC-1121: The core's
file_logger_mutexcannot be reached from the extension. A fork while another thread holds it can hang the child.
Build and Test Infrastructure
- PCBC-1073: A PHP FIT performer is added, and CI builds its image (#261).
- PCBC-1088: The
docker_linux_x86_64job installs the NTS Linux archives into the officialphp:8.x-cliandphp:8.x-cli-alpineimages and round-trips a document (#266). - PCBC-1075, PCBC-1077: macOS x86_64 and arm64 CI builds fixed (#258, #260).
- A Windows build that produces no
php_couchbase.dllfails its job (#265).