Hi everyone, I glad to introduce you new release of PHP SDK.
This release contains internal improvements, as well as new features. Note, that minimum version of libcouchbase required is 2.7.2. This release does not depend on PCS extension anymore. Also all classes, which were previously written in PHP, now implemented Zend C APIs, so do not require extra evaluation on module load or request initialization.
Improved connection management: connections persistent by default, but the library tracks their liveliness and closes idle connections.
Migrate API to \Couchbase namespace (old API still available on toplevel as aliases, see tests/AliasesTest.php)
Refresh API documentation, describe all input options, put everything into single file (see api/) , and prepare them for PHPStorm (JetBrains/phpstorm-stubs#180)
PCBC-443: PCS dependency has been removed and all classes rewritten using Zend C API
Previously if you are using default transcoders, their options were defined in global variables $COUCHBASE_DEFAULT_ENCOPTS and $COUCHBASE_DEFAULT_DECOPTS, so if you were tuning that defaults, now you should do that through INI variables couchbase.encoder.* and couchbase.decoder.*. Full list of supported INI options with detailed description see at API documentation.
Thanks for the update! Especially the API documentation improvements are a big step forward for productivity.
From static code analysis against our Couchbase wrapper codebase I found some other minor breaking changes for us. As we didn’t install the SDK yet, I have no idea if the stubs reflect reality here:
_CouchbaseDefaultViewQuery doesn’t exist (or isn’t documented) any more. It probably was never intended for public use as indicated by the leading underscore, but previously was documented as return type for CouchbaseViewQuery::from(), so it is used by our wrapper code.
_CouchbaseDefaultViewQuery::group_level() has no documented equivalent any more.
CouchbaseViewQuery::stale() doesn’t exist (or isn’t documented) any more. New name which is more consistent with other classes: CouchbaseViewQuery::consistency()
CouchbaseBucketManager::getDesignDocuments() now obviously is CouchbaseBucketManager::listDesignDocuments()
The constructor for CouchbaseN1qlQuery is now obviously private. Before it implicitly was public.
The previously public property CouchbaseN1qlQuery::$options was already marked as “internal” before. Now it doesn’t exist (or isn’t documented) any more.
I also found some probable glitches in the stubs.
The documented return type for CouchbaseBucket::remove(), CouchbaseBucket::upsert() and probably others is \Couchbase\Document. I suppose it is \Couchbase\Document when we pass an array of IDs?
MutationState::from() has no documented return type. PhpStorm interprets that as void, but probably the method still returns MutationState
BucketManager::insertDesignDocument() has no documented return type. PhpStorm interprets that as void, but probably the method still returns something.
Yes. you right, it was not part of the public interface, but now \Couchbase\ViewQuery supports the same set of methods
But it is still accessible. I didn’t found a good way how to document method alias. I’m going to deprecate this method and in favor groupLevel() as all other snake-cased methods. (same for id_range->idRange)
Correct. It is renamed to consistency(), but old name still works as alias, but will be eventually deprecated.
if you know better way to document method aliases, I will update stubs.
again, that is also true, and the now I’m looking after API more carefully. Constructors are private where they should be private.
Yes, it is still accessible, but using it discouraged rather. I think I will expose it as custom() in next release:
Thanks for the fast answer and the fast fixes! Good to know most of the code inspection problems aren’t “real” as the old code should work as before thanks to aliases. It is just a new feeling to have to rely completely on the documentation. Before, we could have a fast look at the PHP part of the source and saw directly what was implemented. We will get used to it, and having to choose, I take the documentation improvements
Ok, that means the function really is void now? In 2.2.4 the function returned bool/true. Probably the check of the return value always was superfluous and/or a bad idea, but we must change that then.
I don’t advocate for this constructor being public - in the opposite. But it is a change which can affect API users and is a breaking change in this sense. We will change our code accordingly.
I don’t know another way than just repeating the method definition, documenting it as “alias of foo” and adding a @see annotation. But the method aliases are anyhow something the API users don’t notice at once: couchbase.php only contains the namespaced class names, not the old ones. I tested adding some class_alias() statements, but PhpStorm didn’t find the methods on the alias classes. So I had to refactor to the namespaced version in order to get the power of code analysis for the Couchbase classes. I find the namespaced version better, so we will make that change happily instead of work with two version in code completion etc. But I can imagine others have other opinions about that.
All in all, we probably won’t have to touch our code too much, so we can do without all the aliases. But nice to know the old code will work.
EDIT: Now I found toplevel.php with the class aliases.
I don’t think that @see will fix the issue, because you still have to browse source method anyway. as you can grep sources and find that old method is aliased to more consistent name, and probably will notice only when I declare alias as deprecated in future.
I also like namespaced version as we do not pollute toplevel as much as previously. Well, we still pollute with aliases, but it is more manageable.
It seems as though \Couchbase\Bucket::unlock() no longer exists. Is this intentional?
Most classes are now final, with most of their methods also being final. I have a thin convenience wrapper around the SDK, and this made it much more difficult to mock things for testing. For example, I would mock \Couchbase\Bucket::get() to ensure that my wrapper properly handled the results. Perhaps this indicates a flaw in my testing methodology, but I’m wondering the value of having everything be final.
Of course it wasn’t intentional, It is very sad that I’ve missed it. The implementation was there, but is not bound to bucket object. I’ve fixed that here http://review.couchbase.org/74875,
We will add this to 2.3.0 release notes, and publish as soon as the release will be ready. Hopefully sooner.
I declared classes and method as final to keep more control over the APIs. I don’t know how you have implemented your wrapper, but you can use aggregation instead of inheritance, and explicitly proxy your methods. In this case all you need is to instantiate your wrapper with test stub instead of real cluster/bucket objects.