[Xapian-discuss] Another PHP 5 wrapper...

[Paul Dixon]

> A very important issue is that it needs to be easy to update the
> bindings.

My approach of "lazy" run-time binding achieves that, but at some cost
to the PHP developer - all the things Daniel pointed out, such as
documentation, IDE support etc.

However, there's no reason why Daniel could not incorporate my base
class into his classes to get the best of both worlds, with
pre-defined and documented methods, but falling back to __call when a
method is not found. It would just need a few tweaks to support method
names using lowerCamelCase.

Similarly, it would be possible to write a test harness which looked
at the available function APIs and checked whether the relevant class
supported that method, for example, checking the function
'database_get_termfreq' would cause it to check if a class called
XapianDatabase was defined and that it had a getTermFreq() method
(obviously a little case  manipulation and other text munging would be
required to pull this off)

This approach would allow existing users of the wrapper to call new
APIs (via the __call trick in the base wrapper class) and allow the
maintainers of the wrapper to easily spot holes in the wrapping for
further enhancement.


> If we're actually going to have PHP code to wrap each method (which
> does have some advantages) I'd favour getting SWIG to generate the
> wrapper code rather than trying to maintain it by hand.  Kevin Ruland
> (the current SWIG PHP maintainer) is looking to move SWIG's PHP support
> in this direction anyway:
>
> http://article.gmane.org/gmane.comp.programming.swig.devel/15958
>
> I was intending to mention Paul's approach to Kevin as an easy way
> for SWIG to provide such wrappers (at least as a first implementation).

I think the lazy-binding approach of my wrapper may send shudders down
many a php developer's spine if it were adopted by SWIG! However,
there's a few techniques in there which aid coercion of object
variables to and from xapian resource variables which might be useful
in machine generation of a full wrapper which doesn't use __call - for
example:

class XapianWritableDatabase extends XapianBase {

  function addDoc(XapianDocument $doc) {

	//turn object pointers into resources
	$args=func_get_args();
	array_walk_recursive($args, array($this, 'coerce_param'));
			
	//call real function		
	$rvalue=call_user_func_array('writabledatabase_adddoc', $args);
	
	return $this->wrap_resource($rvalue);
  }

}

The addDoc method has a parameter list converted from the C++
equivalent, but the internals of the method need no knowledge aside
from the actual function to call, and base class methods
coerce_param() and wrap_resource() ensure you can pass object
variables as parameters which are translated to resources, and any
resource-based return value is wrapped in a class.



> I think we should aim to provide as natural an API to the programmer
> as we can, so for example providing iterators with the native semantics,
> etc is important.  So is operator overloading in languages which support
> it.  And so is following local naming conventions (it's not just the
> Java wrappers which rename methods - so do the C# ones).
>
> I must admit that camelCase as a PHP convention is news to me

PEAR code has used this convention for some time
http://pear.php.net/manual/en/standards.naming.php

The new Zend Framework also adopts this convention
http://framework.zend.com

If other language wrappers have renamed methods then it makes sense to
me that an "official" wrapper follow the PEAR standards.


> Anyway, on to a couple of specific points...
>
> Daniel writes:
> > - target : PHP >= 5.1
>
> I don't really have any idea which PHP versions are prevalent.  I'm
> guessing PHP4 is still fairly widely used and will continue to be for
> a while to come, so it would be good to keep the existing bindings for
> that (possibly with proxy classes reenabled to give an OO interface).

PHP4 is widely used yes, but I'd wager the vast majority of those
installations are shared servers, and so have a much lower likelihood
of being able to install Xapian in the first place.

Developers using PHP5 are most likely making the switch because of the
much improved OO support, and so I'd conclude that there's little
point expending much effort on a PHP4 compatible class wrapper.

> But what's the issue with PHP 5.0 here?  I'm assuming there's something
> useful which was added in 5.1,

Daniel can answer that, I don't *think* I used anything 5.1 specific.
v5.1 did include a lot of bug fixes and some enhancements to the
Standard PHP Library (SPL) which Daniel might have used?


Paul