The PHP bindings for Xapian are packaged in the xapian.so
extension, and largely follow the C++ API. This document lists the differences
and additions. PHP strings and arrays, etc., are converted automatically
in the bindings, so generally it should just work as expected.
The examples subdirectory contains examples showing how to use the
PHP bindings based on the simple examples from xapian-examples:
simpleindex.php,
simplesearch.php.
Assuming you have a suitable version of PHP installed (PHP4 or PHP5), running
configure will automatically enable the PHP bindings, and
make install will install the extension shared library in
the location reported by php-config --extension-dir.
Check that php.ini has a line like extension_dir =
"<location reported by php-config --extension-dir>".
Then add this line to php.ini: extension = xapian.so (or
whatever the library is called - not all UNIX systems use .so
as the extension, and MS Windows uses .dll).
Depending how PHP is setup, you may need to restart the webserver for this change to take effect.
Alternatively you can add the following line to the start of your PHP scripts:
dl('xapian.so');
In PHP5, we translate exceptions thrown by Xapian into PHP Exception objects which are thrown into the PHP script.
Unfortunately, exception handling with try and catch
isn't supported in PHP4, and the alternatives aren't great.
Most C++ exceptions are converted to a PHP fatal error.
However, for exceptions which might be commonly encountered we instead
produce a PHP warning and the method returns null. You can
then check for and handle the exception like so:
$old_error_reporting = error_reporting
if ($old_error_reporting & E_WARNING)
error_reporting($old_error_reporting ^ E_WARNING);
$doc = Database_get_document($database, $docid);
if ($doc != null) {
exit(1);
}
if ($old_error_reporting & E_WARNING)
error_reporting($old_error_reporting);
The following exceptions are currently handled like this (this is a fairly new feature, so feedback on exceptions which should and shouldn't be in this list is particularly welcome):
DocNotFoundError
FeatureUnavailableError
The PHP bindings do not currently use a PHP object oriented style
(unfortunately SWIG's support for this is currently buggy for PHP4 and
unimplemented for PHP5). In order to construct an object, use
$object = new_ClassName(...);. You can't explicitly destroy
an object from PHP, but unset($object); or $object = Null; will cause the destructor
to be called.
Invoke methods on an object using ClassName_method_name($object, ...).
All iterators support next() and equals() methods
to move through and test iterators (as for all language bindings).
MSetIterator and ESetIterator also support prev().
C++ iterators are often dereferenced to get information, eg
(*it). With PHP these are all mapped to named methods, as
follows:
| Iterator | Dereferencing method |
| PositionIterator | get_termpos() |
| PostingIterator | get_docid() |
| TermIterator | get_term() |
| ValueIterator | get_value() |
| MSetIterator | get_docid() |
| ESetIterator | get_termname() |
Other methods, such as MSetIterator.get_document(), are
available unchanged.
MSet objects have some additional methods to simplify access (these work using the C++ array dereferencing):
| Method name | Explanation |
get_hit(index) | returns MSetIterator at index |
get_document_percentage(index) | convert_to_percent(get_hit(index)) |
get_document(index) | get_hit(index).get_document() |
get_docid(index) | get_hit(index).get_docid() |
Xapian::Auto::open_stub(file) is wrapped as open_stub(file)
Xapian::Quartz::open(...) is wrapped as quartz_open(...)
Xapian::InMemory::open() is wrapped as inmemory_open()
Xapian::Remote::open() is wrapped as remote_open() (only
the TCP version is currently wrapped, the "program" version isn't).
Constants are wrapped with the Xapian namespace removed, so
Xapian::DB_CREATE_OR_OPEN is available as
DB_CREATE_OR_OPEN, Xapian::Query::OP_OR is
available as Query_OP_OR, and so on.
In C++ there's a Xapian::Query constructor which takes a query operator and start/end iterators specifying a number of terms or queries, plus an optional parameter. In PHP, this is wrapped to accept an array listing the terms and/or queries (you can specify a mixture of terms and queries if you wish) For example:
subq = new_Query(Query_OP_AND, "hello", "world");
q = new_Query(xapian.Query.OP_AND, array(subq, "foo", new_Query("bar", 2)));
There is an additional method get_matching_terms() which takes
an MSetIterator and returns a list of terms in the current query which
match the document given by that iterator. You may find this
more convenient than using the TermIterator directly.