xapian-bindings/php/docs/index.rst

   1 PHP bindings for Xapian
   2 ***********************
   3
   4 The PHP5 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 As of Xapian version 1.3.2, these bindings require at least PHP 5.5.
   9 (Older versions of PHP are now out of security support, but if you really need
  10 support for them then Xapian 1.2 supports PHP 5.0 and later).  PHP 7 is supported
  11 by a separate set of bindings (this approach was taken due to extensive changes
  12 to PHP's C extension API between PHP 5 and PHP 7).
  13
  14 PHP strings, arrays, etc., are converted automatically to and from the
  15 corresponding C++ types in the bindings, so generally you can pass arguments as
  16 you would expect.  One thing to be aware of though is that SWIG implements
  17 dispatch functions for overloaded methods based on the types of the parameters,
  18 so you can't always pass in a string containing a number (e.g.
  19 ``"42"``) where a number is expected as you usually can in PHP.
  20 You need to
  21 explicitly convert to the type required - e.g. use ``(int)`` to
  22 convert to an integer, ``(string)`` to string, ``(double)``
  23 to a floating point number.
  24
  25 With version 1.2.6 and later, you can subclass Xapian classes in PHP and
  26 virtual methods defined in PHP are called from C++ in the way you'd expect.
  27
  28 PHP has a lot of reserved words of various sorts, which sadly clash with common
  29 method names.  Because of this ``empty()`` methods of various
  30 container-like classes are wrapped as ``is_empty()`` for PHP
  31 and the ``clone()`` method of the ``XapianWeight``
  32 class and subclasses is wrapped as ``clone_object()``.
  33
  34 The ``examples`` subdirectory contains examples showing how to use the
  35 PHP bindings based on the simple examples from ``xapian-examples``:
  36 `simpleindex.php5 <examples/simpleindex.php5>`_,
  37 `simplesearch.php5 <examples/simplesearch.php5>`_,
  38 `simpleexpand.php5 <examples/simpleexpand.php5>`_,
  39 `simplematchdecider.php5 <examples/simplematchdecider.php5>`_.
  40
  41 Note that these examples are written to work with the command line (CLI)
  42 version of the PHP interpreter, not through a webserver.  Xapian's PHP
  43 bindings may of course also be used under CGI, Apache's modphp, ISAPI,
  44 etc.
  45
  46 Installation
  47 ============
  48
  49 Assuming you have a suitable version of PHP installed, running
  50 configure will automatically enable the PHP bindings, and
  51 ``make install`` will install the extension shared library in
  52 the location reported by ``php-config --extension-dir``.
  53
  54 Check that php.ini has a line like ``extension_dir = "<location reported by php-config --extension-dir>"``.
  55
  56
  57 Then add this line to php.ini: ``extension = xapian.so`` (or
  58 whatever the library is called - not all UNIX systems use ``.so``
  59 as the extension, and MS Windows uses ``.dll``).
  60
  61 If you're using PHP as a webserver module (e.g. mod_php with Apache), you
  62 may need to restart the webserver for this change to take effect.
  63
  64 You also need to add ``include&nbsp;"xapian.php"``
  65 to your PHP scripts which use Xapian in order to get the PHP class wrappers.
  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 <http://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 Since Xapian 1.3.2, 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
 172 - ``Xapian::Auto::open_stub(file)`` is wrapped as ``Xapian::auto_open_stub(file)`` (now deprecated)
 173 - ``Xapian::Chert::open()`` is wrapped as ``Xapian::chert_open()`` (now deprecated)
 174 - ``Xapian::InMemory::open()`` is wrapped as ``Xapian::inmemory_open()`` (now deprecated)
 175 - ``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).
 176 - ``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).
 177
 178 Constants
 179 #########
 180
 181 Constants are wrapped as ``const`` members of the appropriate class.
 182 So ``Xapian::DB_CREATE_OR_OPEN`` is available as
 183 ``Xapian::DB_CREATE_OR_OPEN``, ``Xapian::Query::OP_OR`` is
 184 available as ``XapianQuery::OP_OR``, and so on.
 185
 186 Functions
 187 #########
 188
 189 Non-class functions are wrapped in the natural way, so the C++
 190 function ``Xapian::version_string`` is wrapped under the same
 191 name in PHP.
 192
 193 Query
 194 #####
 195
 196 In C++ there's a Xapian::Query constructor which takes a query operator and
 197 start/end iterators specifying a number of terms or queries, plus an optional
 198 parameter.  In PHP, this is wrapped to accept an array listing the terms
 199 and/or queries (you can specify a mixture of terms and queries if you wish)
 200 For example:
 201
 202 ::
 203
 204    $subq = new XapianQuery(XapianQuery::OP_AND, "hello", "world");
 205    $q = new XapianQuery(XapianQuery::OP_AND, array($subq, "foo", new XapianQuery("bar", 2)));
 206
 207
 208
 209 MatchAll and MatchNothing
 210 -------------------------
 211
 212 In Xapian 1.3.0 and later, these are wrapped as static methods
 213 ``XapianQuery::MatchAll()`` and ``XapianQuery::MatchNothing()``.
 214
 215 If you want to be compatible with earlier versions, you can continue to use
 216 ``new XapianQuery('')`` for MatchAll and
 217 ``new XapianQuery()`` for MatchNothing.
 218
 219
 220 Enquire
 221 #######
 222
 223 There is an additional method ``get_matching_terms()`` which takes
 224 an MSetIterator and returns a list of terms in the current query which
 225 match the document given by that iterator.  You may find this
 226 more convenient than using the TermIterator directly.