From ed7a351e352a4a259bd5a7567f7a818679c1fd00 Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Sat, 6 Apr 2024 17:52:10 -0700 Subject: [PATCH 01/15] Add 3.x -> 4.x migration guide --- MIGRATION_FROM_3_x.md | 598 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 598 insertions(+) create mode 100644 MIGRATION_FROM_3_x.md diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md new file mode 100644 index 00000000..83588963 --- /dev/null +++ b/MIGRATION_FROM_3_x.md @@ -0,0 +1,598 @@ +# Migration Guide for 3.x Branch + +Couchbase PHP SDK v4 brought a lot of improvements in API. Some of the changes unfortunately break +compatibility with v3. This guide helps to upgrade application, and highlights the most important +differences. + +API Reference: https://docs.couchbase.com/sdk-api/couchbase-php-client + +## The Components Overview + +The following diagram illustrates architecture of PHP SDK v3: + +```mermaid +block-beta + columns 3 + + developer("Developer") + block:user:2 + columns 2 + Applications + ODMs + Frameworks + Integrations + end + + low_level("Extension\n(exposes high-level API)") + extension("PHP Binary Extension\n(PECL: couchbase)"):2 + + dependencies("System Dependencies") + block:deps:2 + lcb("libcouchbase") + libevent("libevent") + boring_ssl("OpenSSL") + end +``` + + +The following diagram illustrates architecture of PHP SDK v4: + +```mermaid +block-beta + columns 3 + + developer("Developer") + block:user:2 + columns 2 + Applications + ODMs + Frameworks + Integrations + end + + high_level("High-Level API") + library("PHP Library\n(Composer: couchbase/couchbase)"):2 + + low_level("Extension") + extension("PHP Binary Extension\n(PECL: couchbase)"):2 + + dependencies("Static Dependencies") + block:deps:2 + cxx_core("C++ Core SDK") + boring_ssl("BoringSSL") + end +``` + +So let us point to immediate differences: + +1. SDKv4 uses Composer to deliver high-level API classes, while SDKv3 defines everything in the + extension. While it adds extra step for the Developer, it really simplifies maintaining, reduces + potential memory issues, allows to keep documentation consistent and improves IDE integration. + + It is really easy add classes to the application using Composer. + ```bash + composer require couchbase/couchbase + ``` + + the resulting `composer.json` need only two lines to be added: + ```diff + diff --git i/composer.json w/composer.json + index b743a66..88e69da 100644 + --- i/composer.json + +++ w/composer.json + @@ -24,6 +24,8 @@ + "require": { + "php": "^7.4 || ^8.0", + "ext-json": "*", + + "ext-couchbase": "^4.2", + + "couchbase/couchbase": "^4.2", + "monolog/monolog": "^2.3", + "php-di/php-di": "^6.3", + "slim/psr7": "^1.5", + ``` + + In case, the Composer cannot be used, we also have autoloader script `Couchbase\autoload.php`, + that sets up hook to resolve and automatically require SDK classes, but to use this autoloader, + the headers must be installed somewhere in PHP include path, which could be found using one of + the following commands, or in the `phpinfo()` output. + ``` + $ pecl config-get php_dir + /usr/share/pear + ``` + ``` + $ php -r 'printf("%s\n", ini_get("include_path"));' + .:/usr/share/pear:/usr/share/php + ``` + +2. Another important observation is that SDKv4 does not expect any system libraries or headers to be + installed to work and uses statically compiled core implementation (just like all other + wrappers). Also it statically links TLS library to the extension, which, again, simplifies + deployment on Windows platform. + +## Transcoder API + +SDKv3 used non-standard way of specifying encoder and decoder for the document objects for KV API. +This API was inherited from SDKv2, and basically the Developer needed to specify only decoder, or +encoder function in the options. SDKv4 fixes this and instead defines `\Couchbase\Transcoder` +interface which encapsulates all logic. In addition it provides four implementations of it +and uses `\Couchbase\JsonTranscoder` by default. + +Lets say we want to read/write documents without any conversion, just as a binary streams. To do so, +we would need to override transcoder, because otherwise our byte strings will be serialized as JSON +strings. + +Here is how it is done with SDKv3: + +```php +$options = new \Couchbase\ClusterOptions(); +$options->credentials("Administrator", "password"); +$cluster = new \Couchbase\Cluster("couchbase://localhost", $options); +$collection = $cluster->bucket("default")->defaultCollection(); + +$passThruDecoder = function($bytes, $flags, $datatype) { + // do not check anything just return bytes as passed by core + return $bytes; +}; + +$passThruEncoder = function($value) { + // do not do conversion, and return zeroes for datatype and flags + return [$value, 0x00, 0x00]; +}; + + +// Mutation operations in SDKv3 explicitly ask for encoder callable +$options = new \Couchbase\UpsertOptions(); +$options->encoder($passThruEncoder); +$collection->upsert("foo", "BINARY DATA: \xDE\xAD\xBE\xEF", $options); + +// Retrieval operation in SDKv3 only allow decoder callable +$options = new \Couchbase\GetOptions(); +$options->decoder($passThruDecoder); +$res = $collection->get("foo", $options); +var_dump($res->content()); +``` + +With SDKv4 we ship `\Couchbase\RawBinaryTranscoder`, which could be reimplemented as following: + +```php +class PassThruTranscoder implements \Couchbase\Transcoder +{ + public function encode($value): array + { + return [ + $value, + (new \Couchbase\TranscoderFlags(\Couchbase\TranscoderFlags::DATA_FORMAT_BINARY))->encode(), + ]; + } + + public function decode(string $bytes, int $flags) + { + return $bytes; + } +} + +// RawBinaryTranscoder like any other implementation has static method getInstance() returning +// singleton object. +$passThruTranscoder = new PassThruTranscoder(); + +$options = new \Couchbase\UpsertOptions(); +$options->transcoder($passThruTranscoder); +$collection->upsert("foo", "BINARY DATA: \xDE\xAD\xBE\xEF", $options); + +$options = new \Couchbase\GetOptions(); +$options->transcoder($passThruTranscoder); +$res = $collection->get("foo", $options); +var_dump($res->content()); +``` + +## Error Handling + +SDKv4 moved exceptions into `\Couchbase\Exception` namespace, so if the application used to catch +and handle exceptions from SDK, those places should update to use new names. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SDKv3 exceptionSDKv4 exception
\Couchbase\AuthenticationException \Couchbase\Exception\AuthenticationFailureException
\Couchbase\BadInputException \Couchbase\Exception\InvalidArgumentException
+
    +
  • \Couchbase\BucketMissingException
    • +
  • \Couchbase\KeyspaceNotFoundException
    • +
+ 		\Couchbase\Exception\BucketNotFoundException
\Couchbase\CasMismatchException \Couchbase\Exception\CasMismatchException
\Couchbase\CollectionMissingException \Couchbase\Exception\CollectionNotFoundException
\Couchbase\DurabilityException + One of the more specific exceptions. +
    +
  • \Couchbase\Exception\DurabilityAmbiguousException
    • +
  • \Couchbase\Exception\DurabilityImpossibleException
    • +
  • \Couchbase\Exception\DurabilityLevelNotAvailableException
    • +
  • \Couchbase\Exception\DurableWriteInProgressException
    • +
  • \Couchbase\Exception\DurableWriteReCommitInProgressException
    • +
+
\Couchbase\DmlFailureException + The SDK will detect underlying error that caused the query to fail and throw + specific exception. +
    +
  • \Couchbase\Exception\CasMismatchException
    • +
  • \Couchbase\Exception\DocumentExistsException
    • +
  • \Couchbase\Exception\DocumentLockedException
    • +
  • etc.
    • +
+
\Couchbase\DocumentNotFoundException \Couchbase\Exception\DocumentNotFoundException
\Couchbase\IndexFailureException \Couchbase\Exception\IndexFailureException
\Couchbase\IndexNotFoundException \Couchbase\Exception\IndexNotFoundException
\Couchbase\InvalidRangeException \Couchbase\Exception\DeltaInvalidException
\Couchbase\KeyDeletedException Removed
\Couchbase\KeyExistsException \Couchbase\Exception\DocumentExistsException
\Couchbase\KeyLockedException \Couchbase\Exception\DocumentLockedException
\Couchbase\ParsingFailureException \Couchbase\Exception\ParsingFailureException
\Couchbase\PartialViewException Removed
\Couchbase\PathExistsException \Couchbase\Exception\PathExistsException
\Couchbase\PathNotFoundException \Couchbase\Exception\PathNotFoundException
\Couchbase\PlanningFailureException \Couchbase\Exception\PlanningFailureException
\Couchbase\PreparedStatementFailureException \Couchbase\Exception\PreparedStatementFailureException
+
    +
  • \Couchbase\QuotaLimitedException
    • +
  • \Couchbase\RateLimitedException
    • +
+ 		Rate and Quota limit exceptions redesigned, and the SDK will not use them.
\Couchbase\RequestCanceledException \Couchbase\Exception\RequestCanceledException
\Couchbase\ScopeMissingException \Couchbase\Exception\ScopeNotFoundException
\Couchbase\ServiceNotAvailableException \Couchbase\Exception\ServiceNotAvailableException
\Couchbase\TempFailException \Couchbase\Exception\TemporaryFailureException
\Couchbase\TimeoutException \Couchbase\Exception\TimeoutException
\Couchbase\ValueTooBigException \Couchbase\Exception\ValueTooLargeException
+
    +
  • \Couchbase\AnalyticsException
    • +
  • \Couchbase\BindingsException
    • +
  • \Couchbase\InvalidConfigurationException
    • +
  • \Couchbase\InvalidStateException
    • +
  • \Couchbase\KeyValueException
    • +
  • \Couchbase\NetworkException
    • +
  • \Couchbase\QueryErrorException
    • +
  • \Couchbase\QueryException
    • +
  • \Couchbase\QueryServiceException
    • +
  • \Couchbase\SearchException
    • +
  • \Couchbase\SubdocumentException
    • +
  • \Couchbase\ViewException
    • +
+ 		+ All generic exceptions mapped to \Couchbase\Exception\CouchbaseException or to one + of the new, more specific exceptions. +
    +
  • \Couchbase\Exception\CollectionExistsException
    • +
  • \Couchbase\Exception\CompilationFailureException
    • +
  • \Couchbase\Exception\ConsistencyMismatchException
    • +
  • \Couchbase\Exception\DatasetExistsException
    • +
  • \Couchbase\Exception\DatasetNotFoundException
    • +
  • \Couchbase\Exception\DataverseExistsException
    • +
  • \Couchbase\Exception\DataverseNotFoundException
    • +
  • \Couchbase\Exception\DecodingFailureException
    • +
  • \Couchbase\Exception\DesignDocumentNotFoundException
    • +
  • \Couchbase\Exception\DocumentIrretrievableException
    • +
  • \Couchbase\Exception\DocumentNotJsonException
    • +
  • \Couchbase\Exception\DocumentNotLockedException
    • +
  • \Couchbase\Exception\EncodingFailureException
    • +
  • \Couchbase\Exception\FeatureNotAvailableException
    • +
  • \Couchbase\Exception\GroupNotFoundException
    • +
  • \Couchbase\Exception\IndexExistsException
    • +
  • \Couchbase\Exception\IndexNotReadyException
    • +
  • \Couchbase\Exception\InternalServerFailureException
    • +
  • \Couchbase\Exception\JobQueueFullException
    • +
  • \Couchbase\Exception\LinkExistsException
    • +
  • \Couchbase\Exception\LinkNotFoundException
    • +
  • \Couchbase\Exception\NumberTooBigException
    • +
  • \Couchbase\Exception\PathInvalidException
    • +
  • \Couchbase\Exception\PathMismatchException
    • +
  • \Couchbase\Exception\PathTooBigException
    • +
  • \Couchbase\Exception\PathTooDeepException
    • +
  • \Couchbase\Exception\PermissionDeniedException
    • +
  • \Couchbase\Exception\ScopeExistsException
    • +
  • \Couchbase\Exception\TransactionCommitAmbiguousException
    • +
  • \Couchbase\Exception\TransactionException
    • +
  • \Couchbase\Exception\TransactionExpiredException
    • +
  • \Couchbase\Exception\TransactionFailedException
    • +
  • \Couchbase\Exception\TransactionOperationFailedException
    • +
  • \Couchbase\Exception\UnambiguousTimeoutException
    • +
  • \Couchbase\Exception\UnsupportedOperationException
    • +
  • \Couchbase\Exception\UserExistsException
    • +
  • \Couchbase\Exception\UserNotFoundException
    • +
  • \Couchbase\Exception\ValueInvalidException
    • +
  • \Couchbase\Exception\ValueTooDeepException
    • +
  • \Couchbase\Exception\ViewNotFoundException
    • +
  • \Couchbase\Exception\XattrCannotModifyVirtualAttributeException
    • +
  • \Couchbase\Exception\XattrInvalidKeyComboException
    • +
  • \Couchbase\Exception\XattrUnknownMacroException
    • +
  • \Couchbase\Exception\XattrUnknownVirtualAttributeException
    • +
+
+ +## String-backed Enumerations + +In SDKv4 various enumerations and constants changed their types from `int` to `string` to reduce +potential issues. In general nothing has to be changed here, but in some cases names of the types +slightly changed to be more consistent with other SDKs. + +### View Consistency + + + + + + + + + + + + + + + + + + + + + + +
SDKv3SDKv4
\Couchbase\ViewScanConsistency::NOT_BOUNDED (0)\Couchbase\ViewConsistency::NOT_BOUNDED ("notBounded")
\Couchbase\ViewScanConsistency::REQUEST_PLUS (1)\Couchbase\ViewConsistency::REQUEST_PLUS ("requestPlus")
\Couchbase\ViewScanConsistency::UPDATE_AFTER (2)\Couchbase\ViewConsistency::UPDATE_AFTER ("updateAfter")
+ +### View Ordering + + + + + + + + + + + + + + + + + + +
SDKv3SDKv4
\Couchbase\ViewOrdering::ASCENDING (0)\Couchbase\ViewOrdering::ASCENDING ("ascending")
\Couchbase\ViewOrdering::DESCENDING (1)\Couchbase\ViewOrdering::DESCENDING ("descending")
+ +### Query Consistency + + + + + + + + + + + + + + + + + + + + + + +
SDKv3SDKv4
\Couchbase\QueryScanConsistency::NOT_BOUNDED (1)\Couchbase\QueryScanConsistency::NOT_BOUNDED ("notBounded")
\Couchbase\QueryScanConsistency::REQUEST_PLUS (2)\Couchbase\QueryScanConsistency::REQUEST_PLUS ("requestPlus")
\Couchbase\QueryScanConsistency::STATEMENT_PLUS (3)Removed
+ +### Query Profile + + + + + + + + + + + + + + + + + + + + + + +
SDKv3SDKv4
\Couchbase\QueryProfile::OFF (1)\Couchbase\QueryProfile::OFF ("off")
\Couchbase\QueryProfile::PHASES (2)\Couchbase\QueryProfile::PHASES ("phases")
\Couchbase\QueryProfile::TIMINGS (3)\Couchbase\QueryProfile::TIMINGS ("timings")
+ +### Analytics Consistency + + + + + + + + + + + + + + + + + + +
SDKv3SDKv4
""\Couchbase\AnalyticsScanConsistency::NOT_BOUNDED ("notBounded")
"request_plus"\Couchbase\AnalyticsScanConsistency::REQUEST_PLUS ("requestPlus")
+ +## Changing Timeout Values + +SDKv3 did not allow to set timeouts through `\Couchbase\ClusterOptions`, and the application have to +rely on connection string (that is handled by `libcouchbase` eventually), or use setter methods on +the `\Couchbase\Bucket` instance. + +The table below shows correspondence of timeout values between `Bucket` object setters and +`ClusterOptions` in the new API. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SDKv3 (in microseconds)SDKv4 (in milliseconds)
Bucket::operationTimeout()ClusterOptions::keyValueTimeout()
Bucket::viewTimeout()ClusterOptions::viewTimeout()
Bucket::n1qlTimeout()ClusterOptions::queryTimeout()
Bucket::durabilityInterval()Removed
Bucket::durabilityTimeout()ClusterOptions::keyValueDurableTimeout()
Bucket::configTimeout()ClusterOptions::bootstrapTimeout()
Bucket::configDelay()Removed
Bucket::configNodeTimeout()Removed
Bucket::htconfigIdleTimeout()Removed
Bucket::configPollInterval()ClusterOptions::configPollInterval()
Bucket::httpTimeout() + One of the service-related should be used: +
    +
  • ClusterOptions::viewTimeout()
    • +
  • ClusterOptions::queryTimeout()
    • +
  • ClusterOptions::searchTimeout()
    • +
  • ClusterOptions::analyticsTimeout()
    • +
  • ClusterOptions::managementTimeout()
    • +
+
+ +## PHP INI Entries + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SDKv3SDKv4
+ couchbase.log_level +
    +
  • FATAL
    • +
  • ERROR
    • +
  • WARN
    • +
  • INFO
    • +
  • DEBUG
    • +
  • TRACE
    • +
+ 		+ couchbase.log_level +
    +
  • fatal
    • +
  • error
    • +
  • wrning
    • +
  • info
    • +
  • debug
    • +
  • trace
    • +
+
couchbase.encoder.formatRemoved
couchbase.encoder.compressionRemoved
couchbase.encoder.compression_thresholdRemoved
couchbase.encoder.compression_factorRemoved
couchbase.decoder.json_arraysRemoved
couchbase.pool.max_idle_time_seccouchbase.persistent_timeout
couchbase.allow_fallback_to_bucket_connectionRemoved
From 6c9196c3dd4bd5272d9c630721a39468b3a2f00c Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:48:06 -0700 Subject: [PATCH 02/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index 83588963..5b021459 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -1,7 +1,7 @@ # Migration Guide for 3.x Branch -Couchbase PHP SDK v4 brought a lot of improvements in API. Some of the changes unfortunately break -compatibility with v3. This guide helps to upgrade application, and highlights the most important +Couchbase PHP SDK v4 brought a lot of improvements to the API. Some of the changes unfortunately break +compatibility with v3. This guide helps upgrade applications, and highlights the most important differences. API Reference: https://docs.couchbase.com/sdk-api/couchbase-php-client From 83ec91708d100367edbf549f0284a1fe26bab4f8 Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:48:12 -0700 Subject: [PATCH 03/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index 5b021459..1720ab60 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -8,7 +8,7 @@ API Reference: https://docs.couchbase.com/sdk-api/couchbase-php-client ## The Components Overview -The following diagram illustrates architecture of PHP SDK v3: +The following diagram illustrates the architecture of PHP SDK v3: ```mermaid block-beta From a8a7329531fe6aed7a748387893b72b96f69728f Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:48:17 -0700 Subject: [PATCH 04/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index 1720ab60..d6bc28d8 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -6,7 +6,7 @@ differences. API Reference: https://docs.couchbase.com/sdk-api/couchbase-php-client -## The Components Overview +## Components Overview The following diagram illustrates the architecture of PHP SDK v3: From 321fa72e5ccff5a7b78d91fd4a37962603a18cca Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:48:23 -0700 Subject: [PATCH 05/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index d6bc28d8..002309b2 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -35,7 +35,7 @@ block-beta ``` -The following diagram illustrates architecture of PHP SDK v4: +The following diagram illustrates the architecture of PHP SDK v4: ```mermaid block-beta From 2cf44b77461bc760918e33ee4178104eb2c162bf Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:48:32 -0700 Subject: [PATCH 06/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index 002309b2..17e7dca0 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -63,7 +63,7 @@ block-beta end ``` -So let us point to immediate differences: +So let us point out immediate differences: 1. SDKv4 uses Composer to deliver high-level API classes, while SDKv3 defines everything in the extension. While it adds extra step for the Developer, it really simplifies maintaining, reduces From a53121f9a4f9d29138f68a285f0335df05a2c63d Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:48:38 -0700 Subject: [PATCH 07/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index 17e7dca0..1d724878 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -111,10 +111,10 @@ So let us point out immediate differences: ## Transcoder API -SDKv3 used non-standard way of specifying encoder and decoder for the document objects for KV API. -This API was inherited from SDKv2, and basically the Developer needed to specify only decoder, or -encoder function in the options. SDKv4 fixes this and instead defines `\Couchbase\Transcoder` -interface which encapsulates all logic. In addition it provides four implementations of it +SDKv3 used a non-standard way of specifying an encoder and decoder for the document objects for the KV API. +This API was inherited from SDKv2, where the developer needed to specify a decoder or +encoder function in the options. SDKv4 fixes this and instead defines the `\Couchbase\Transcoder` +interface which encapsulates all the logic. Additionally, it provides four implementations of it and uses `\Couchbase\JsonTranscoder` by default. Lets say we want to read/write documents without any conversion, just as a binary streams. To do so, From 5ba44676b1028f5156b6284202bdc746b15f7917 Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:48:47 -0700 Subject: [PATCH 08/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index 1d724878..59ac5172 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -66,7 +66,7 @@ block-beta So let us point out immediate differences: 1. SDKv4 uses Composer to deliver high-level API classes, while SDKv3 defines everything in the - extension. While it adds extra step for the Developer, it really simplifies maintaining, reduces + extension. While it adds an extra step for the developer, it really simplifies maintenance, reduces potential memory issues, allows to keep documentation consistent and improves IDE integration. It is really easy add classes to the application using Composer. From b4fc5f0bdf2b0f7cabf3576894ec4324e6159106 Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:49:58 -0700 Subject: [PATCH 09/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index 59ac5172..f0eb5a85 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -227,8 +227,8 @@ and handle exceptions from SDK, those places should update to use new names. \Couchbase\DmlFailureException - The SDK will detect underlying error that caused the query to fail and throw - specific exception. + The SDK will detect the underlying error that caused the query to fail and throw + the specific exception.
  • \Couchbase\Exception\CasMismatchException
  • \Couchbase\Exception\DocumentExistsException
    • From 8e11926646a36428dafdc2050265802ec8bd5f19 Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:50:14 -0700 Subject: [PATCH 10/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index f0eb5a85..6ad18c8e 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -117,8 +117,8 @@ encoder function in the options. SDKv4 fixes this and instead defines the `\Couc interface which encapsulates all the logic. Additionally, it provides four implementations of it and uses `\Couchbase\JsonTranscoder` by default. -Lets say we want to read/write documents without any conversion, just as a binary streams. To do so, -we would need to override transcoder, because otherwise our byte strings will be serialized as JSON +Let's say we want to read/write documents without any conversion, just as a binary streams. To do so, +we would need to override the transcoder, because otherwise our byte strings will be serialized as JSON strings. Here is how it is done with SDKv3: From d9b69e57ddade4bcdfdb71618239e569d4de7335 Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:50:21 -0700 Subject: [PATCH 11/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index 6ad18c8e..c7c2691c 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -152,7 +152,7 @@ $res = $collection->get("foo", $options); var_dump($res->content()); ``` -With SDKv4 we ship `\Couchbase\RawBinaryTranscoder`, which could be reimplemented as following: +With SDKv4 we ship `\Couchbase\RawBinaryTranscoder`, which could be reimplemented as the following: ```php class PassThruTranscoder implements \Couchbase\Transcoder From 0a26ca1887af26c599ed8e765eef19ddbe587427 Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:50:30 -0700 Subject: [PATCH 12/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index c7c2691c..1372ad68 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -74,7 +74,7 @@ So let us point out immediate differences: composer require couchbase/couchbase ``` - the resulting `composer.json` need only two lines to be added: + the resulting `composer.json` needs only two lines to be added: ```diff diff --git i/composer.json w/composer.json index b743a66..88e69da 100644 From 1ba794daa4fce11150a1843f56c54c37a6e06ced Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:51:05 -0700 Subject: [PATCH 13/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index 1372ad68..a8711123 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -91,9 +91,9 @@ So let us point out immediate differences: "slim/psr7": "^1.5", ``` - In case, the Composer cannot be used, we also have autoloader script `Couchbase\autoload.php`, - that sets up hook to resolve and automatically require SDK classes, but to use this autoloader, - the headers must be installed somewhere in PHP include path, which could be found using one of + In case Composer cannot be used, we also have autoloader script `Couchbase\autoload.php`, + that sets up a hook to resolve and automatically require SDK classes, but to use this autoloader, + the headers must be installed somewhere in the PHP include path, which could be found using one of the following commands, or in the `phpinfo()` output. ``` $ pecl config-get php_dir From d656da88f30bc2799a6f8a02031e04827acd2191 Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:51:14 -0700 Subject: [PATCH 14/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index a8711123..f0c13aa7 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -105,9 +105,9 @@ So let us point out immediate differences: ``` 2. Another important observation is that SDKv4 does not expect any system libraries or headers to be - installed to work and uses statically compiled core implementation (just like all other - wrappers). Also it statically links TLS library to the extension, which, again, simplifies - deployment on Windows platform. + installed to work and uses a statically compiled core implementation (just like all other + wrappers). Additionally, it statically links the TLS library to the extension, which, again, simplifies + deployment on the Windows platform. ## Transcoder API From 4bb99bdd5dd53a40d3804ccbcc8b6ed8b6ae7e7f Mon Sep 17 00:00:00 2001 From: Sergey Avseyev Date: Tue, 9 Apr 2024 11:51:22 -0700 Subject: [PATCH 15/15] Update MIGRATION_FROM_3_x.md Co-authored-by: Mateusz --- MIGRATION_FROM_3_x.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/MIGRATION_FROM_3_x.md b/MIGRATION_FROM_3_x.md index f0c13aa7..25111518 100644 --- a/MIGRATION_FROM_3_x.md +++ b/MIGRATION_FROM_3_x.md @@ -187,8 +187,8 @@ var_dump($res->content()); ## Error Handling -SDKv4 moved exceptions into `\Couchbase\Exception` namespace, so if the application used to catch -and handle exceptions from SDK, those places should update to use new names. +SDKv4 moved exceptions into the `\Couchbase\Exception` namespace, so if the application used to catch +and handle exceptions from the SDK, those places should update to use the new names.