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.

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.

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;
}

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

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
  }

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.

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.