Zeta Components - high quality PHP components

• Tutorial
• API
• Solr_schema

eZ Components - Search

Introduction

The search component allows you to index and search documents. A document consists of an object. A definition maps the object's properties to fields of a document, just like the PersistentObject component. The indexing process takes the document and indexes the fields depending on the data type. The searching part allows you to search for documents in the index with a rich query language.

Class overview

This section gives you an overview of the main classes in the Search component.

ezcSearchSession

This class provide access to the search index for both indexing and searching. All operations towards the index go through this class which is configured with a search handler and a definition manager.

ezcSearchSolrHandler

The handler that uses Solr for indexing and searching.

ezcSearchQueryBuilder

A class that allows you to build a search query from a search string.

ezcSearchQuery

An interface to building complex search queries in case ezcSearchQueryBuilder is not up to the task.

Search Handlers

Search handlers provide the link between the abstract query and document interfaces to the mechanism that actually stores the index, and allows querying for documents. Not all handlers handle all the different query words or datatypes in the index, but effort is to put in to make as much use of the handler's functionality as possible.

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. ?>

Definition Managers

A definition manager maps properties of an object to fields in a search document. As most search handlers support fields with arbitrary names, you don't actually provide the name of the fields in the search index. Instead, the mapping configures several things for an object's property.

First of all, every document type needs an ID field. This ID will uniquely define a document in the search index. There can only be one ID field, and there has to be one. For each field, you have to define the data type, and optionally you can configure:

• The importance of that field (boost factor)

• Whether the field should be a part of the resulting document

• Whether the field supports multiple values

• Whether highlighting should be performed for this field on result documents

Definitions can be supplied in two ways. The embedded manager retrieves the definitions from the document classes directly, whereas the xml manager uses external XML file to read definitions from.

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:

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/' );
?>

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:

The RelaxNG-Compressed schema is:

Search Session

The search session is responsible for indexing documents, and searching for documents. The session object requires both a search handler and a definition manager. The handler is used for storing the index, while the definition manager is used to find the definition that maps object's properties to search index fields. Creating a session is simple, as is demonstrated in the following example:

1. <?php
2. require_once 'tutorial_autoload.php';
4. $handler = new ezcSearchSolrHandler;
5. $manager = new ezcSearchEmbeddedManager;
7. $session = new ezcSearchSession( $handler, $manager );
8. ?>

Indexing

With the session created, it is time to index documents. Before we can index anything we need to create an object and create the definition. For this tutorial we'll reuse the definition from the Embedded Manager section and create a class out of this. Each class that you want to index through the Search component needs to implement the ezcBasePersistable interface. This interfaces defines two methods: getState() and setState() as well as the requirement that the constructor should be able to be called without any arguments. Those methods are used for fetching and re-creating the state of this object, similarly to what PersistentObject requires.

To see everything in perspective, the full class follows here, including the definition method:

1. <?php
2. class Article implements ezcBasePersistable, ezcSearchDefinitionProvider
3. {
4.     public  $id;
5.     public  $title;
6.     private $body;
7.     private $published;
8.     private $url;
9.     private $type;
11.     function __construct( $id = null, $title = null, $body = null, $published = null, $url = null, $type = null )
12.     {
13.         $this->id = $id;
14.         $this->title = $title;
15.         $this->body = $body;
16.         $this->published = $published;
17.         $this->url = $url;
18.         $this->type = $type;
19.     }
21.     function getState()
22.     {
23.         $state = array(
24.             'id' => $this->id,
25.             'title' => $this->title,
26.             'body' => $this->body,
27.             'published' => $this->published,
28.             'url' => $this->url,
29.             'type' => $this->type,
30.         );
31.         return $state;
32.     }
34.     function setState( $state )
35.     {
36.         foreach ( $state as $key => $value )
37.         {
38.             $this->$key = $value;
39.         }
40.     }
42.     static public function getDefinition()
43.     {
44.         $n = new ezcSearchDocumentDefinition( __CLASS__ );
45.         $n->idProperty = 'id';
46.         $n->fields['id']        = new ezcSearchDefinitionDocumentField( 'id', ezcSearchDocumentDefinition::TEXT );
47.         $n->fields['title']     = new ezcSearchDefinitionDocumentField( 'title', ezcSearchDocumentDefinition::TEXT, 2, true, false, true );
48.         $n->fields['body']      = new ezcSearchDefinitionDocumentField( 'body', ezcSearchDocumentDefinition::TEXT, 1, false, false, true );
49.         $n->fields['published'] = new ezcSearchDefinitionDocumentField( 'published', ezcSearchDocumentDefinition::DATE );
50.         $n->fields['url']       = new ezcSearchDefinitionDocumentField( 'url', ezcSearchDocumentDefinition::STRING );
51.         $n->fields['type']      = new ezcSearchDefinitionDocumentField( 'type', ezcSearchDocumentDefinition::STRING, 0, true, false, false );
53.         return $n;
54.     }
55. }
56. ?>

The ezcBasePersistable interface is also compatible with PersistentObject, although there the interface is not enforced.

After we've created the class and definition, indexing an object is relatively simple. After instantiation, indexing the document is done by calling the index() method of the session as you can see in the next example:

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. // instantiate article
10. $article = new Article();
11. $article->title = "A test article to show indexing.";
12. $article->body  = <<<ENDBODY
13. This is the body of the text, nothing interesting now
14. as this is just an example.
15. ENDBODY;
16. $article->published = time();
17. $article->url       = "/article/1";
18. $article->type      = "article";
20. // index
21. $session->index( $article );
22. ?>

If you are indexing a large amount of documents, it's wise to wrap this into an indexing transaction. For the handlers that support this, this will optimize the indexing process. See the ezcSearchSession->beginTransaction() documentation.

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:

Searching

After documents are indexed, they are searchable. Building a search query can be done in two ways. The Query Language approach is the most powerful one, but is more complex. Alternatively you can use the Query Builder approach which lets you feed it a string and it will build the query from that string.

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. ?>