Skip to content

4.6.0

Latest

Choose a tag to compare

@avsej avsej released this 07 Nov 01:16
· 11 commits to main since this release
4.6.0
688c55a

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.0

The 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, in couchbase.so or php_couchbase.dll. The -abi archives are no longer produced (#266).

    • An INI file that loads couchbase_X_Y_Z has to change to extension=couchbase.
    • The extension's functions live in Couchbase\Extension and its exceptions in Couchbase\Exception. The versioned Couchbase\Extension_X_Y_Z namespaces, ExtensionNamespaceResolver and the COUCHBASE_EXTENSION_NAMESPACE constant are removed, and so is the couchbase_extension_abi row of phpinfo().
    • The library checks only that the couchbase module 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.
  • Minimum PHP version -- PHP 8.2 is the minimum supported version. PECL refuses to install 4.6.0 on PHP 8.1.

  • Interface methods -- ClusterInterface gains disconnect() and CollectionInterface gains getReplica(). 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_persistent applies 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 as couchbase_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) raises AuthenticationFailureException, not InternalServerFailureException (#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 with ReplicaIndex::FIRST, SECOND or THIRD.

    • DocumentNotFoundOnReplicaException, ReplicaIndexOutOfBoundsException and ReplicaIndexCurrentlyUnavailableException report the replica-specific failures.
    • Over couchbase2://, getReplica() throws UnsupportedOperationException.
  • PCBC-1070: Search score fusion -- SearchOptions::scoring() selects how hybrid search results are scored (#257).

    • SearchScoringReciprocalRankFusion and SearchScoringRelativeScoreFusion require Couchbase Server 8.1 or later, and raise FeatureNotAvailableException on older servers.
    • SearchScoringNone works on any server.
  • PCBC-974: Retry strategy per operation -- Key/value options accept retryStrategy() with RetryStrategy::BEST_EFFORT or RetryStrategy::FAIL_FAST (#271). Any other value throws InvalidArgumentException.

    • With FAIL_FAST, a mutation on a locked document throws DocumentLockedException at 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.
  • PCBC-1058: Cluster::disconnect() -- Closes the cluster's connection and removes it from the cache (#269).

    • The next operation throws CouchbaseException carrying cluster_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 with cluster_closed. A cluster created afterwards with the same arguments bootstraps a new connection.
    • Over couchbase2://, disconnect() throws UnsupportedOperationException.

Bug Fixes

  • PCBC-1089: Logging in a forked child -- A process forked with couchbase.log_level set 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_path set, a child forked without Cluster::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.
  • 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() and max() keep fractional bounds as floats. A range with min -1.5 reported -1 (#263).

  • PCBC-1081: Legacy durability strings -- An unknown persistTo or replicateTo string raises InvalidArgumentException naming the value, and the document is not written (#262).

  • View skip option -- A view query with ViewOptions::skip() no longer throws InvalidArgumentException (#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_attributes API (#256).

Deprecations

  • PCBC-1070: SearchOptions::disableScoring() is deprecated in favour of scoring(new SearchScoringNone()).

Known Issues

  • CXXCBC-1121: The core's file_logger_mutex cannot 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_64 job installs the NTS Linux archives into the official php:8.x-cli and php:8.x-cli-alpine images 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.dll fails its job (#265).