xapian-bindings/php/docs/index.rst

   1 PHP bindings for Xapian
   2 ***********************
   3
   4 The PHP bindings for Xapian are packaged in the ``xapian``
   5 extension.  The PHP API provided by this extension largely follows Xapian's C++
   6 API.  This document lists the differences and additions.
   7
   8 PHP strings, arrays, etc., are converted automatically to and from the
   9 corresponding C++ types in the bindings, so generally you can pass arguments as
  10 you would expect.  One thing to be aware of though is that SWIG implements
  11 dispatch functions for overloaded methods based on the types of the parameters,
  12 so you can't always pass in a string containing a number (e.g.
  13 ``"42"``) where a number is expected as you usually can in PHP.
  14 You need to
  15 explicitly convert to the type required - e.g. use ``(int)`` to
  16 convert to an integer, ``(string)`` to string, ``(double)``
  17 to a floating point number.
  18
  19 You can subclass Xapian classes in PHP and virtual methods defined in PHP are
  20 called from C++ in the way you'd expect.
  21
  22 PHP has a lot of reserved words of various sorts, which sadly clash with common
  23 method names.  Because of this ``empty()`` methods of various
  24 container-like classes are wrapped as ``is_empty()`` for PHP.
  25
  26 The ``examples`` subdirectory contains examples showing how to use the
  27 PHP bindings based on the simple examples from ``xapian-examples``:
  28 `simpleindex.php8 <examples/simpleindex.php8>`_,
  29 `simplesearch.php8 <examples/simplesearch.php8>`_,
  30 `simpleexpand.php8 <examples/simpleexpand.php8>`_,
  31 `simplematchdecider.php8 <examples/simplematchdecider.php8>`_.
  32
  33 Note that these examples are written to work with the command line (CLI)
  34 version of the PHP interpreter, not through a webserver.  Xapian's PHP
  35 bindings may of course also be used under CGI, Apache's modphp, ISAPI,
  36 etc.
  37
  38 Installation
  39 ============
  40
  41 This version of the bindings only support PHP >= 8.0  If you need support
  42 for PHP 5.x or 7.x, you'll need to use Xapian 1.4.21 or earlier instead.
  43
  44 If you want to install from source you'll need to `download the source
  45 code <https://xapian.org/download>`_ if you haven't already done so.
  46
  47 Assuming you have a suitable version of PHP installed, running
  48 configure will automatically enable the PHP bindings, and
  49 ``make install`` will install the extension shared library in
  50 the location reported by ``php-config --extension-dir``.
  51
  52 Check that php.ini has a line like ``extension_dir = "<location reported by php-config --extension-dir>"``.
  53
  54
  55 Then add this line to php.ini: ``extension=xapian``
  56
  57 If you're using PHP as a webserver module (e.g. mod_php with Apache), you
  58 may need to restart the webserver for this change to take effect.
  59
  60 Previous versions of these bindings for PHP < 8 also required you to add
  61 ``include&nbsp;"xapian.php"`` to your PHP scripts which use Xapian, but
  62 this is not necessary with versions which support PHP8 (1.4.22 and newer).
  63 To write code which supports both you can use::
  64
  65     if (PHP_MAJOR_VERSION < 8) include "xapian.php";
  66
  67 Exceptions
  68 ##########
  69
  70 Exceptions thrown by Xapian are translated into PHP Exception objects
  71 which are thrown into the PHP script.
  72
  73 Object orientation
  74 ##################
  75
  76 These PHP bindings use a PHP object oriented style.
  77
  78 To construct an object, use
  79 ``$object = new XapianClassName(...);``.  Objects are destroyed
  80 when they go out of scope - to explicitly destroy an object you can use
  81 ``unset($object);`` or ``$object = Null;``
  82
  83 You invoke a method on an object using ``$object->method_name()``.
  84
  85 Unicode Support
  86 ###############
  87
  88 The Xapian::Stem, Xapian::QueryParser, and
  89 Xapian::TermGenerator classes all assume text is in UTF-8.  If you want
  90 to index strings in a different encoding, use the PHP `iconv function <https://secure.php.net/iconv>`_ to convert them to UTF-8 before passing them to Xapian, and when reading values back from Xapian.
  91
  92 Iterators
  93 #########
  94
  95 Xapian's iterators (except ``XapianLatLongCoordsIterator``)
  96 are wrapped as PHP iterators, so can be used in ``foreach``.
  97
  98 There's one important thing to beware of currently - the ``rewind()`` method
  99 on ``XapianPositionIterator``, ``XapianPostingIterator``,
 100 ``XapianTermIterator`` and ``XapianValueIterator`` currently does nothing.  We
 101 can't make it simply throw an exception, as ``foreach`` calls ``rewind()``
 102 before iteration starts - each iterator needs to track if ``next()`` has been
 103 called yet, and we've not yet implemented machinery for that.  This doesn't
 104 affect the standard pattern of iterating once with ``foreach``, but if you want
 105 to iterate a second time, you can't reuse the iterator (but it will currently
 106 fail quietly).
 107
 108 You can safely call ``rewind()`` on ``XapianESetIterator`` and
 109 ``XapianMSetIterator``.
 110
 111 The ``current()`` method returns the result of dereferencing the iterator
 112 in C++ (e.g. for a ``TermIterator``, it returns the term as a string - see
 113 the section below for more details) and the ``key()`` method returns the
 114 iterator object, which you can call other methods on, for example::
 115
 116     foreach ($db->allterms_begin() as $k => $term) {
 117         print "{$k->get_termfreq()}\t$term\n";
 118     }
 119
 120 As well as the standard PHP iterator methods, MSetIterator and ESetIterator
 121 also support ``prev()`` to go back one place.
 122
 123 Iterator dereferencing
 124 ######################
 125
 126 C++ iterators are often dereferenced to get information, eg
 127 ``(*it)``. With PHP these are all mapped to named methods, as
 128 follows:
 129
 130 +------------------+----------------------+
 131 | Iterator         | Dereferencing method |
 132 +==================+======================+
 133 | PositionIterator |   ``get_termpos()``  |
 134 +------------------+----------------------+
 135 | PostingIterator  |   ``get_docid()``    |
 136 +------------------+----------------------+
 137 | TermIterator     |   ``get_term()``     |
 138 +------------------+----------------------+
 139 | ValueIterator    |   ``get_value()``    |
 140 +------------------+----------------------+
 141 | MSetIterator     |   ``get_docid()``    |
 142 +------------------+----------------------+
 143 | ESetIterator     |   ``get_term()``     |
 144 +------------------+----------------------+
 145
 146 Other methods, such as ``MSetIterator::get_document()``, are
 147 available unchanged.
 148
 149 MSet
 150 ####
 151
 152 MSet objects have some additional methods to simplify access (these
 153 work using the C++ array dereferencing):
 154
 155 +------------------------------------+----------------------------------------+
 156 | Method name                        |            Explanation                 |
 157 +====================================+========================================+
 158 | ``get_hit(index)``                 |   returns MSetIterator at index        |
 159 +------------------------------------+----------------------------------------+
 160 | ``get_document_percentage(index)`` | ``convert_to_percent(get_hit(index))`` |
 161 +------------------------------------+----------------------------------------+
 162 | ``get_document(index)``            | ``get_hit(index)->get_document()``     |
 163 +------------------------------------+----------------------------------------+
 164 | ``get_docid(index)``               | ``get_hit(index)->get_docid()``        |
 165 +------------------------------------+----------------------------------------+
 166
 167
 168 Database Factory Functions
 169 ##########################
 170
 171 - ``Xapian::Remote::open(...)`` is wrapped as ``Xapian::remote_open(...)`` (both the TCP and "program" versions are wrapped - the SWIG wrapper checks the parameter list to decide which to call).
 172 - ``Xapian::Remote::open_writable(...)`` is wrapped as ``Xapian::remote_open_writable(...)`` (both the TCP and "program" versions are wrapped - the SWIG wrapper checks the parameter list to decide which to call).
 173
 174 Constants
 175 #########
 176
 177 Constants are wrapped as ``const`` members of the appropriate class.
 178 So ``Xapian::DB_CREATE_OR_OPEN`` is available as
 179 ``Xapian::DB_CREATE_OR_OPEN``, ``Xapian::Query::OP_OR`` is
 180 available as ``XapianQuery::OP_OR``, and so on.
 181
 182 Functions
 183 #########
 184
 185 Non-class functions are wrapped in the natural way, so the C++
 186 function ``Xapian::version_string`` is wrapped under the same
 187 name in PHP.
 188
 189 Query
 190 #####
 191
 192 In C++ there's a Xapian::Query constructor which takes a query operator and
 193 start/end iterators specifying a number of terms or queries, plus an optional
 194 parameter.  In PHP, this is wrapped to accept an array listing the terms
 195 and/or queries (you can specify a mixture of terms and queries if you wish)
 196 For example:
 197
 198 ::
 199
 200    $subq = new XapianQuery(XapianQuery::OP_AND, "hello", "world");
 201    $q = new XapianQuery(XapianQuery::OP_AND, array($subq, "foo", new XapianQuery("bar", 2)));
 202
 203
 204
 205 MatchAll and MatchNothing
 206 -------------------------
 207
 208 These are wrapped as static methods
 209 ``XapianQuery::MatchAll()`` and ``XapianQuery::MatchNothing()``.
 210
 211 If you want to be compatible with version 1.2.x of Xapian's PHP5 bindings, you
 212 can continue to use ``new XapianQuery('')`` for MatchAll and
 213 ``new XapianQuery()`` for MatchNothing.
 214
 215
 216 Enquire
 217 #######
 218
 219 There is an additional method ``get_matching_terms()`` which takes
 220 an MSetIterator and returns a list of terms in the current query which
 221 match the document given by that iterator.  You may find this
 222 more convenient than using the TermIterator directly.