In support of the upcoming Couchbase Server 4.5 release and some innovation in the PHP community with PHP 7, we are enhancing our PHP SDK. Today I’d like to announce the third Beta, which brings a couple of new fetures along with internal fixes and improvements. In this blog post we will demonstrate some of them.
Sub-Document API
We already wrote about this API previously, but this time lets show some PHP. We assume you have installed Couchbase 4.5 beta as a minimum and have setup the enhanced sample bucket travel-sample. First lets do some service code, where we instantiate a connection to bucket, and also define a utility function to report on a random hotel.
|
1 2 3 4 5 6 7 8 9 |
$cluster = new CouchbaseCluster('couchbase://localhost'); $bucket = $cluster->openBucket('travel-sample'); function report($name, $publicLikes, $firstServiceRating) { printf("Hotel "%s" has %d public likes. First rating for Service is %dn", $name, count($publicLikes), $firstServiceRating); } |
Okay now we are ready. The Sub-Document API allows you save network traffic while operating on large documents by using fine-grained control, for example lets pull some of the properties from the hotel_10025:
|
1 2 3 4 5 6 7 8 |
$res = $bucket->lookupIn('hotel_10025') ->get('name') ->get('public_likes') ->get('reviews[0].ratings.Service') ->execute(); report($res->value[0]['value'], $res->value[1]['value'], $res->value[2]['value']); // => Hotel "Medway Youth Hostel" has 8 public likes. First rating for Service is 5 |
Here and later accessor methods accept path as a first argument. This is similar to the N1QL path as described in the documentation. If you get this document using the regular API, you will see that is isn’t the smallest one and contains lots of information about the place, and with lookupIn you are transferring only data you are interested in. It become more important when you’d like to amend small bits in the huge document. As an example, let’s add one more person to public_likes, adjust the hotel name and remove one of the ratings.
|
1 2 3 4 5 6 |
$bucket->mutateIn('hotel_10025') ->replace('name', 'Medway Adult Hostel') ->arrayAppend('public_likes', 'John Doe') ->remove('reviews[0]') ->execute(); |
The code is pretty self-explanatory. If you would like to use optimistic locking, just pass CAS value as a second argument to mutateIn. The complete list of mutation operators is in the API reference https://docs.couchbase.com/sdk-api/couchbase-php-client-2.2.0beta3/classes/CouchbaseMutateInBuilder.html. Let’s display what we have after the change, but this time we will use the shortcut for lookupIn with multiple get operators:
|
1 2 3 4 5 |
$res = $bucket->retrieveIn('hotel_10025', 'name', 'public_likes', 'reviews[0].ratings.Service'); report($res->value[0]['value'], $res->value[1]['value'], $res->value[2]['value']); // => Hotel "Medway Youth Hostel" has 9 public likes. First rating for Service is 3 |
Index Management
Previously to list, create or remove indexes, it was necessary to manually craft the N1QL statement. In the upcoming PHP SDK 2.2 there will be a new API simplifying this task by exposing handy functions on BucketManager, much like for Couchbase Views. Let’s see what indexes are defined on the travel-sample by default:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
$manager = $bucket->manager(); $res = $manager()->listN1qlIndexes(); foreach ($res as $index) { printf("Index %s.%s", $index->keyspace, $index->name); if ($index->condition) { printf("ntwith condition: %s", $index->condition); } if (count($index->fields) > 0) { printf("nton fields: %s", join(', ', $index->fields)); } printf("n"); } |
It should output something like this:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
Index travel-sample.def_primary Index travel-sample.def_airportname on fields: `airportname` Index travel-sample.def_city on fields: `city` Index travel-sample.def_faa on fields: `faa` Index travel-sample.def_icao on fields: `icao` Index travel-sample.def_name_type with condition: (`_type` = "User") on fields: `name` Index travel-sample.def_route_src_dst_day with condition: (`type` = "route") on fields: `sourceairport`, `destinationairport`, (distinct (array (`v`.`day`) for `v` in `schedule` end)) Index travel-sample.def_schedule_utc on fields: array (`s`.`utc`) for `s` in `schedule` end Index travel-sample.def_sourceairport on fields: `sourceairport` Index travel-sample.def_type on fields: `type` |
The following example demonstrates creating indexes on name:
|
1 2 3 4 |
$manager->createN1qlPrimaryIndex(); $manager->createN1qlIndex('ex_name', array('name')); $manager->createN1qlIndex('ex_srcdst, array('sourceairport','destinationairport'), '`type` = "route"`); |
Removing indexes is not a little harder:
|
1 2 3 |
$manager->dropN1qlPrimaryIndex(); $manager->dropN1qlIndex('ex_name'); |
Before I close, I’d like to show one small but in some cases important change we’ve got in the beta3 release. The CAS value has always been opaque in Couchbase protocol as well as in SDKs, but in PHP it was even hidden from application developer behind the PHP resource reference, which means that it is hard to pass it around easily (for example to render onto HTML page). In this release we encode the CAS as a string token, so it is still opaque, but much easier to serialize it.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
$res = $bucket->get('airline_10'); var_dump($res); //=> object(CouchbaseMetaDoc)#5 (4) { // ["error"]=> // NULL // ["value"]=> // object(stdClass)#4 (7) { // ["id"]=> // int(10) // ["type"]=> // string(7) "airline" // ["name"]=> // string(11) "40-Mile Air" // ["iata"]=> // string(2) "Q5" // ["icao"]=> // string(3) "MLA" // ["callsign"]=> // string(8) "MILE-AIR" // ["country"]=> // string(13) "United States" // } // ["flags"]=> // int(33554438) // ["cas"]=> // string(11) "jq25pb4ckd0" // } |
If you are not familiar with what CAS is, you can learn it by example here: https://github.com/couchbase/php-couchbase/blob/master/examples/cas/cas_replace.php
And finally, to install this release, use the following command (make sure you have libcouchbase 2.6.0+ installed):
|
1 2 |
pecl install couchbase-2.2.0beta3 |
That’s all for now. We plan one more Beta release befor GA with even more features. If you encounter any issues, please post directly to the Couchbase Communities site at https://www.couchbase.com/community/. Additionally, bugs can be reported directly through our issues tracker available here: https://www.couchbase.com/issues/browse/PCBC/
Stay tuned.
