The 3.0 API breaks the existing 2.0 APIs in order to provide a number of improvements.
Collections and Scopes are introduced.
The Document class and structure has been completely removed from the API, and the returned value is now Result.
Retry behaviour is more proactive, and lazy bootstrapping moves all error handling to a single place.
Individual behaviour changes across services are explained here.
6.5@sdk:shared:partial$migration.adoc
6.5@sdk:shared:partial$migration.adoc
As an example here is a KeyValue document fetch:
$getResult = $collection->get("key", (new GetOptionsl())->timeout(3000000));Compare this to a N1QL query:
$queryResult = $cluster->query("select 1=1", (new QueryOptions())->timeout(3000000));6.5@sdk:shared:partial$migration.adoc
6.5@sdk:shared:partial$migration.adoc
6.5@sdk:shared:partial$migration.adoc
As with 2.x release, the primary source of artifacts is the release notes page, where we publish links to pre-built binaries, as well as to source tarballs.
SDK 3.x supports PHP interpreters from 7.2 upwards.
From 3.0 onwards, binaries are available for Windows with the OpenSSL dependency. Note, that OpenSSL DLLs are not distributed in the archive and must be installed separately (see the official OpenSSL page for more details).
Bootstrapping the SDK is staged now, so the application has to create a Cluster object first, and then open the Bucket and Collection if necessary.
As in SDK 2.x there is no explicit shutdown, and all underlying connections still kept in the cache, for reusing in
future requests.
The connection idle time is controlled by the couchbase.pool.max_idle_time_sec PHP INI setting.
SDK 3.x allows the performance of Queries on the Cluster level, so it is not necessary to open a bucket anymore.
SDK 3.x does not allow the use of SASL PLAIN mechanism by default, instead it restricts to SCRAM-SHA{1,256,512}.
SDK 3.x actively uses Exceptions to signal errors.
Instead of using single \Couchbase\Exception, as in SDK 2.x, now we use a hierarchy of exceptions, which allows the handling of errors in a more reliable way:
try {
$collection->get("foo");
} catch (\Couchbase\KeyNotFoundException $ex) {
$collection->upsert("foo", ["bar" => 42]);
}Instead of SDK 2.x’s:
try {
$bucket->get("foo");
} catch (\Couchbase\Exception $ex) {
if ($ex->getCode() == COUCHBASE_KEYNOTFOUND) {
$bucket->upsert("foo", ["bar" => 42]);
}
}SDK 3.x still relies on native types and supports the json_encode API from the standard json.so module (therefore it still has to be loaded before couchbase.so).
But the igbinary.so transcoder is no longer supported.
Most of the KV APIs have moved from bucket-level (in SDK 2.x) to collection-level (in SDK 3.x).
For servers which don’t support collections, the application should obtain the default collection using the bucket->defaultCollection() function.
The following table describes the SDK 2 KV APIs and their equivalents in SDK 3:
| SDK 2 | SDK 3 |
|---|---|
|
|
|
|
- |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The BinaryCollection mentioned above could be retrieved from the regular collection object using the $collection->binary() method.
Ib SDK 3.x, the API for Query was improved and now it is more consistent with other endpoints.
$query = N1qlQuery::fromString('SELECT airportname FROM `travel-sample` WHERE city=$city AND type=$type');
$query->namedParams(['city' => "Los Angeles", 'type' => "airport"]);
$result = $bucket->query($query);
foreach ($result->rows as $row) {
printf("%s\n", $row->airportname);
}$options = new QueryOptions();
$options->namedParameters(['city' => "Los Angeles", 'type' => "airport"]);
$result = $cluster->query('SELECT airportname FROM `travel-sample` WHERE city=$city AND type=$airport', $options);
foreach ($result->rows() as $row) {
printf("%s\n", $row['airportname']);
}Analytics queries in SDK3 have their own API entry point.
$query = AnalyticsQuery::fromString('SELECT * FROM dataset WHERE type = $type');
$query->namedParams(['type' => "airport"]);
$result = $bucket->query($query);
foreach ($result->rows as $row) {
printf("%s\n", $row->airportname);
}$options = new AnalyticsQueryOptions();
$options->namedParameters(['type' => "airport"]);
$result = $cluster->analyticsQuery('SELECT * FROM dataset WHERE type = $type', $options);
foreach ($result->rows() as $row) {
printf("%s\n", $row['airportname']);
}In SDK 3, query options and index name has been extracted from the query object.
$queryPart = SearchQuery::matchPhrase("hop beer");
$query = new SearchQuery("beer-search", $queryPart);
$query->limit(3)->fields("name");
$result = $this->bucket->query($query);
foreach ($result->hits() as $hit) {
printf("%s - %f\n", $hit->id, $hit->score);
}$query = new MatchPhraseSearchQuery("hop beer");
$options = new SearchOptions();
$options->limit(3);
$result = $cluster->search("beer-search", $query, $options);
foreach ($result->rows() as $row) {
printf("%s - %f\n", $row['id'], $row['score']);
}The most noticeable change in the Views API for SDK 3.x is the change of names for consistency control settings.
$query = ViewQuery::from('design_name', 'test');
$query->consistency(ViewQuery::UPDATE_BEFORE);
$res = $bucket->query($query);
foreach ($res->rows as $row) {
printf("%s\n", $row->id);
}$options = new ViewOptions();
$options->scanConsistency(ViewScanConsistency::REQUEST_PLUS);
$res = $bucket->viewQuery('design_name', 'test', $options);
foreach ($res->rows() as $row) {
printf("%s\n", $row->id());
}In SDK 2, the management APIs were centralized in the ClusterManager at the cluster level and the BucketManager at the bucket level.
Since SDK 3 provides more management APIs, they have been split up into their respective domains.
For example, when in SDK 2 you needed to remove a bucket you would call ClusterManager.removeBucket — you will now find it under BucketManager.dropBucket.
And, creating a N1QL index now lives in the QueryIndexManager, which is accessible through the Cluster.
The following table provides a mapping from the SDK 2 management APIs to those of SDK 3:
| SDK 2 | SDK 3 |
|---|---|
|
removed |
|
|
- |
|
|
|
|
|
|
|
|
|
|
|
|
|
| SDK 2 | SDK 3 |
|---|---|
|
removed |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|