Solr

This handler uses Apache's Solr as backend. It accesses Solr over TCP/IP as a web service. Solr is a very capable search provider, with many features.

Using the handler is relatively easy. You basically only have to instantiate the handler class which then can be passed to the ezcSearchSession constructor:

1. <?php
2. require_once 'tutorial_autoload.php';
4. // on localhost with the default port
5. $handler = new ezcSearchSolrHandler;
7. // on another host with a different port
8. $handler = new ezcSearchSolrHandler( '10.0.2.184', 9123 );
9. ?>

Solr requires a schema to work. This scheme defines how data types work and allows for many more customizations. The default schema that comes with Solr requires a few minor changes to make it work with the Search component. This schema should be used as a basis for the Search component.

Zend_Search_Lucene

The component also provides a backend based on Zend's Lucene implementation. This backend has many limitations compared to Solr, such as missing multi-valued field support, no data-type support and a much lower performance. In order to use this backend, you need to have a specific autoload function as well as the Zend Framework installed and included in the PHP included path. An example on how to use it follows:

1. <?php
2. // load the normal ezc autoload mechanism with some tricks
3. require_once 'tutorial_autoload.php';
5. // add the location of the zend framework to the include path, this can of
6. course also be done in php.ini
7. ini_set( 'include_path', ini_get( 'include_path' ) . ':/home/derick/dev/ZendFramework-1.7.4-minimal/library' );
9. // define the autoload function that can load Zend framework classes
10. function zend_autoload( $className )
11. {
12. if ( strpos( $className, '_' ) !== false )
13. {
14. $file = str_replace( '_', '/', $className ) . '.php';
15. $val = require_once( $file );
16. return ( $val == 0 );
17. }
18. }
20. // reset the autoload stack, register the zend_autoload mechanism and
21. // re-register the original eZ Component's autoload() mechanism.
22. spl_autoload_register( 'zend_autoload' );
23. spl_autoload_register( '__autoload' );
25. // open the handler
26. $handler = new ezcSearchZendLuceneHandler( '/tmp/lucene' );
27. ?>

Embedded Manager

The ezcSearchEmbeddedManager retrieves the definition from a class that implements the ezcSearchDefinitionProvider interface. This interfaces specifies the getDefinition() method that should be implemented by the classes to return the document's definition mappings. An example of the implementation of the getDefinition() method is:

static public function getDefinition()
{
    $n = new ezcSearchDocumentDefinition( __CLASS__ );
    $n->idProperty = 'id';
    $n->fields['id']        = new ezcSearchDefinitionDocumentField( 'id', ezcSearchDocumentDefinition::TEXT );
    $n->fields['title']     = new ezcSearchDefinitionDocumentField( 'title', ezcSearchDocumentDefinition::TEXT, 2, true, false, true );
    $n->fields['body']      = new ezcSearchDefinitionDocumentField( 'body', ezcSearchDocumentDefinition::TEXT, 1, false, false, true );
    $n->fields['published'] = new ezcSearchDefinitionDocumentField( 'published', ezcSearchDocumentDefinition::DATE );
    $n->fields['url']       = new ezcSearchDefinitionDocumentField( 'url', ezcSearchDocumentDefinition::STRING );
    $n->fields['type']      = new ezcSearchDefinitionDocumentField( 'type', ezcSearchDocumentDefinition::STRING, 0, true, false, false );

    return $n;
}

Basically what this method does is construct an ezcSearchDocumentDefinition object containing all the field definitions. It's required to have an ID property. It's recommended to use a TEXT data type for this, although it is not required. See the section Data Types on the differences between data types.

Each field is then added to the fields property as a ezcSearchDefinitionDocumentField object. The field index should be the same as the first argument to the constructor of this class. By default the type will be ezcSearchDefinitionDocumentField::TEXT. Subsequent arguments control the importance (boost) of a field, whether it should be part of the result, whether multiple values for this field are accepted and whether it should be selected for highlighting.

XML Manager

The ezcSearchXmlManager uses XML files to obtain a document definition from. The manager is configured with the directory where the XML definition files can be found in the constructor:

1. <?php
2. $xm = new ezcSearchXmlManager( 'search-defs/' );
3. ?>

The names of the definition files are required to be name-of-class-in-lower-case.xml. This means that for the class Article the file article.xml is being read. The file itself is a simple XML file. The file below demonstrates the same definition as the one in the example in Embedded Manager:

<?xml version="1.0"?>
<document>
    <field type="id">id</field>
    <field type="text" highLight="true" boost="2">title</field>
    <field inResult="false" type="html">body</field>
    <field type="date">published</field>
    <field type="string">url</field>
    <field highLight="true" type="string">type</field>
</document>

The RelaxNG-Compressed schema is:

default namespace = "http://components.ez.no/Search"

start =
  element document {
    field+
  }
field =
  element field {
    attribute type { xsd:string },
	attribute highLight { 'true' | 'false' }?,
	attribute inResult { 'true' | 'false' }?,
	attribute multi { 'true' | 'false' }?,
	attribute boost { xsd:float }?,
	string
  }

Data Types

The Search component understands many data types, but they might not always be representable by every handler. The table below explains the different data types that are available:

Query Language

The ezcSearchQuery interface defines all the methods that handlers should implement to realize the query language for every handler. This interface defines methods such as where(), lOr() and between() - very similar to what the ezcQuerySelect and ezcQueryExpression classes provide. The following example shows how to use the query language:

1. <?php
2. require_once 'tutorial_autoload.php';
4. // setup
5. $handler = new ezcSearchSolrHandler;
6. $manager = new ezcSearchEmbeddedManager;
7. $session = new ezcSearchSession( $handler, $manager );
9. // initialize a pre-configured query
10. $q = $session->createFindQuery( 'Article' );
12. $searchWord = 'test';
14. // where either body or title contains thr $searchWord
15. $q->where(
16. $q->lOr(
17. $q->eq( 'body', $searchWord ),
18. $q->eq( 'title', $searchWord )
19. )
20. );
22. // limit the query and order
23. $q->limit( 10 );
24. $q->orderBy( 'title' );
26. // add a facet on url (not very useful)
27. $q->facet( 'url' );
29. // run the query and show titles for found documents
30. $r = $session->find( $q );
32. foreach( $r->documents as $res )
33. {
34. echo $res->document->title, "\n";
35. }
36. ?>

The result of the query is returned in the form of an ezcSearchResult object. This contains the documents, but also information about facets and pagination. See the documentation of the ezcSearchResult class for more information.

Query Builder

The query builder approach allows you to use more powerful query strings instead of having to use the API to create queries. With this you can allow query strings such as foo -bar, while still searching in multiple fields. Be aware however, that it depends on the handlers whether it will actually return the expected results. The query builder interface will most likely work best if you're only searching in one field only. At the moment the query builder understands +, -, grouping ( with '(' and ')' ), AND and OR modifiers, as well as phrases (enclosed in ").

An example that searches in two fields (body and title) follows:

1. <?php
2. require_once 'tutorial_autoload.php';
4. // setup
5. $handler = new ezcSearchSolrHandler;
6. $manager = new ezcSearchEmbeddedManager;
7. $session = new ezcSearchSession( $handler, $manager );
9. // initialize a pre-configured query
10. $q = $session->createFindQuery( 'Article' );
12. // where either body or title contains test but not article
13. $searchWord = 'test -article';
15. // run the query builder to search for the $searchWord in body and title
16. $qb = new ezcSearchQueryBuilder();
17. $qb->parseSearchQuery( $q, $searchWord, array( 'body', 'title' ) );
19. // run the query and show titles for found documents, and its score
20. $r = $session->find( $q );
22. foreach( $r->documents as $res )
23. {
24. echo $res->document->score, ", ", $res->document->title, "\n";
25. }
26. ?>