Migration from 1.x to 2.x PHP API

#1

I have been using the 1.x PHP API for some time now. It works for me but I accept that I’ll need to move to the 2.x API sometime but I’d really love to see some sort of write-up on what the differences are to help aid my migration from 1.x to 2.x. Does such a resource exist?

#2

Hey ksnyde,

I would suggest taking a look at these resources for further information:
http://blog.couchbase.com/php-sdk-200-developer-preview
http://blog.couchbase.com/php-sdk-200-developer-preview-2
http://blog.couchbase.com/php-sdk-200-beta-2
http://blog.couchbase.com/php-sdk-200-beta
http://docs.couchbase.com/prebuilt/php-sdk-2.0/topics/overview.html

Cheers, Brett

#3

Brett,

I’ve clicked through all of your links and they all lead largely to the same thing: a reference to the new API and installation instructions (note: your last link redirects to the 3.0 general documentation … not sure what was there before). Your first link at least describes the motivations/philosophy toward the change but the rest are not at all helpful in answering the question I posed.

I guess the compact answer to my question is … there is no migration documentation. I know you guys are moving fast but getting your customer base to follow you requires some basic blocking and tackling. A quick review of what changes have been made and a few “common gotchas” would make the process a less more onerous.

Other questions I think would be very helpful for people to know:

  • What versions of libcouchbase match up with the SDK versions?
  • How long will the 1.x SDK be supported and does it work with Couchbase 3.0
  • Does the new SDK work with all Couchbase 2.x versions?
  • Besides consistency in API structure – which is pointed to as the primary reason for the change in your first link – are there any other benefits that people should be considering when upgrading?
#4

I had the same conclusion than you. My approach was to develop a Couchbase class with the same methods than in the v1 but which internally uses the v2 calls.
That way your existing code should work.

It might not be full featured yet (i only developped the methods i used before) and some behaviour might be different than with the v1 but it is the closer i could do with the available (lack of) documentation…

If you want to try it : https://github.com/kevinhatry/phpcb-migration

Also to answer, to the best of my knowledge, with the 2.0.2 PHP client library, libcouchbase should be at least 2.4.5.
It works against the server CE 3.0.1 (i tested it). I don’t think it will work against a v2 server but i did not test it.
What is sure is that, with my class, PHP code using the v1 calls should work with a v3 server using the v2 client lib !

#5

@excession, great to hear I’m not alone (or first) in this problem. Thanks very much for sharing your abstraction layer. I think it will help me understand the scope of change and its good to hear that v1 versus v2 aren’t so different in approach that abstraction is achievable with just a mapping strategy.

#6

@excession, just looked through the code. Great stuff. Documented, clear. Very good. Brett, you should talk to the CB exec’s and see if you can get @excession a paycheck for doing Couchbase’s work for them. :smile:

#7

There are a few differences, for some of which i was planning to create a post here …
Like :

  • setting multiple keys with different values is not possible with one command
  • a counter is now retrieved as a string instead of a number (wrong flags i guess)

But globally it seems to work out.
Also i forgot to say but to ease the migration : it is possible to access a v3 server using the v1 client lib and libcouchbase. So your old code can work with both environment if you can do something like :


<?php
if (!class_exists('Couchbase',false)) { require('path to my Couchbase class'); }
#8

Hey everyone!

I was puzzled with the same questions about a month ago and even emailed Brett with somewhat angry email. Originally I chose Couchbase from a dozen of other nosql solutions because of its simplicity and solid API. And currently there’s a mess with different versions of servers, C SDK, PHP modules. ksnyde really asks questions many would love to be answered.

I tried setting up the environment with the new version today but without success so far. With linux it’s quite easy, but I also have a Windows based dev machine and it’s really not obvious how to make it work. Also, I see many bugreports here for the new SDK version so I decided to keep using v.1.2 of the PHP driver for now. Can’t see any problems with the 3.0 server. Not sure about the performance of the old SDK as I couldn’t test.

The docs for the new SDK are quite poor too.

#9

Hey ksnyde,

What versions of libcouchbase match up with the SDK versions?

It is usually expected that the most recent version of libcouchbase at the time of any PHP SDK release will be the required library, this is due to the fact that most updates to the PHP SDK utilize new features and/or fixes from the latest libcouchbase. The inverse is not true however, and any later version of libcouchbase should function fine with an older version of the PHP SDK.

How long will the 1.x SDK be supported and does it work with Couchbase 3.0

The 1.x SDK’s are expected to be fully compatible with new libcouchbase versions, in addition to this, all Couchbase Server versions >=2.0 are expected to function with all versions of all SDKs.

Does the new SDK work with all Couchbase 2.x versions?

See Above.

Besides consistency in API structure – which is pointed to as the primary reason for the change in your first link – are there any other benefits that people should be considering when upgrading?

Whilst the previous 1.x series of SDKs continue to be supported for bug fixes and other critical issues, new features of Couchbase Server which require client integration will not be back-ported to the 1.x series. In addition to this, many performance enhancements are made to only the latest edition of the clients.

Cheers, Brett

#10

Hey excessions,

I’d like to mention some things about the differences you posted:

setting multiple keys with different values is not possible with one command

All storage methods permit passing of an array of values to them permitting you to perform multiple storage operations at the same time, using different values for each. Note that you should pass a ‘value’ option on each of these, and the value itself will be ignore. For example:

<?php
  $bucket->upsert(array(
    'key1' => array('value' => 'value1'),
    'key2' => array('value' => 'value2')
  ));

a counter is now retrieved as a string instead of a number (wrong flags i guess)

In the 2.x SDK, the counter method should be returning numeric values at all times. If you do a get on a value that is used by counter, the value should also be decoded as an integer. Could you provide an example where this does not occur?

Cheers, Brett

#11

Hi Brett,

thanks for the tip regarding upserting multiple values. My reading of the library source code was not sufficient to reveal that !
I tested it and it works as you said.

Regarding the counter operation, i saw the counter() itself returns an integer, but what i meant is that when you retrieve (via get()) a counter you get a string. Sample code :


<?php
    $var = 'crash__'.getmypid().'_'.time();

    $cluster = new CouchbaseCluster('couchbase://10.0.0.100','test','');
    $bucket = $cluster->openBucket('test');

    $resp = $bucket->counter($var,1,array('initial' => 1));
    var_dump($resp); // int : as expected

    $resp = $bucket->get($var);
    var_dump($resp); // string

    $resp = $bucket->counter($var,1);
    var_dump($resp); // int : as expected

    $resp = $bucket->get($var);
    var_dump($resp); // string

Here is the output :


object(CouchbaseMetaDoc)#4 (4) {
  ["error"]=>
  NULL
  ["value"]=>
  int(1)
  ["flags"]=>
  int(0)
  ["cas"]=>
  resource(4) of type (CouchbaseCAS)
}
object(CouchbaseMetaDoc)#5 (4) {
  ["error"]=>
  NULL
  ["value"]=>
  string(1) "1"
  ["flags"]=>
  int(0)
  ["cas"]=>
  resource(5) of type (CouchbaseCAS)
}
object(CouchbaseMetaDoc)#4 (4) {
  ["error"]=>
  NULL
  ["value"]=>
  int(2)
  ["flags"]=>
  int(0)
  ["cas"]=>
  resource(6) of type (CouchbaseCAS)
}
object(CouchbaseMetaDoc)#5 (4) {
  ["error"]=>
  NULL
  ["value"]=>
  string(1) "2"
  ["flags"]=>
  int(0)
  ["cas"]=>
  resource(7) of type (CouchbaseCAS)
}