Drupal's ambitious search module provides a framework for building searches of all kinds. By isolating the tasks involved in searching, and allowing the actual search implementations to be handled by other modules, the search framework sets the stage for all sorts of creative search applications. This article, which applies to Drupal 6, explores the structure of the search framework by following the steps needed to execute a search.

Stucture of a search

Here are the basic steps involved in searching:

1. Build a search index.
2. Build a search form.
3. Accept a POST request from the form.
4. Redirect POST to GET with search query values expressed in the URL.
5. Parse search query values.
6. Construct search based on query values.
7. Return formatted results.

Build a search index

The search module's API for indexing HTML content is very simple.

Example 1: search_index is the way you put stuff into the search index.

$sid is the unique id for a piece of content, $type corresponds to the name of the search implementation (see 'name' $op for hook_search), and $text is the HTML that is to be indexed.

Build a search form

The basic search form is simply a text field with a submit button. This form is available by default to every module that implements search using hook_search. The main method for extending this form is through hook_form_alter (see node.module, node_form_alter). It is also possible to build search functionality using other tools that don't rely totally on the search framework. See views_fastsearch for one such hybrid approach.

Accept a POST request from the form

The search_menu and the search_view functions cooperate to make sure that any incoming POST requests for search get redirected to the same path using GET, only with the POST information expressed as part of the GET request.

Example 2: search_menu and search_view.

In search_menu it can be seen how a path is being built for every search module that implements a search. You can see this in action on any Drupal installation with search.module enabled at the path http://example.com/search. The Content and the Users tabs come from the node and user modules' search implementations, respectively. An interesting and important detail is the path description: $items['search/'. $name .'/%menu_tail']. The %menu_tail bit passes everything it matches as a parameter, verbatim, without splitting it into further segments. This is important if you want to be able to search for the string "foo/bar", for example. Normally that would be split into path segments based on the forward slash, but %menu_tail prevents the splitting.

Figure 1: A basic search form with Content and User tabs.

Redirect POST to GET with search query values expressed in the URL

The first lines of search_view promise to redirect to GET, but the mechanism for doing this isn't visible in the code:

Example 2: Detail of search_view. Only do something on GET.

Clearly the search itself doesn't happen unless there is no POST form_id value (ie it is a GET request), but how does the redirect happen? The answer lies deep within the handling of the search form:

Example 3: Search form validation and submission.

When the search form is submitted, the values first go to search_form_validate(). The sole purpose of the validation is to make sure the processed search keys (the values of the form submission), are passed on to the submit handler. The submit handler, search_form_submit(), does the unusual task of validating the form (checking if there are actually keys, or if an empty form was submitted). It can be debated whether that validation actually belongs in the search_form_validate function. More interesting to us, however, is the setting of $form_state['redirect']. This is how POSTed search forms get redirected via GET with the search query in the URL. The Forms API will do the redirect after the submit handler has finished.

This process is one of the first mysteries of the search module that often confuses people when they attempt to understand its inner workings. Despite being somewhat mystical in its behavior, the POST -> GET redirect has a very practical advantage: search result pages can be bookmarked.

Parse search query values

The one thing that virtually every function needs in the process of doing a search is the $keys variable that contains the search query. In Drupal 6, the entire search query is represented as a string. The function search_get_keys() can be used to fetch this string, and it is a simple function that looks first to the path, and then to the submitted form values in order to find a keyword query. Whatever is found is stored statically in the function and cannot be changed during the lifetime of the request.

Management of this keyword query string is an interesting issue, especially in the context of the advanced search form. The search module offers two functions, search_query_insert($keys, $option, $value = '') and search_query_extract($keys, $option), which aid in the manipulation of the query string. If you call search_query_extract("foo nid:4711", "nid"), you get the value 4711 in return. If you call search_query_insert("bar", "uid", 42), you get "bar uid:42" in return. Neither of these functions actually interact with search_get_keys, however, so they cannot be used to fetch or manipulate the statically cached keys. See node_form_alter and the $op = 'search' part of node_search for usage examples of these functions. Note in particular how the form is always used as the storage mechanism for the search query string.

Construct search based on query values

The search framework expects modules to use the parsed search query string to do a search for values and return a structured array of results. This process gets triggered in search_view, which calls search_data, which is a wrapper first and foremost for this code: $results = module_invoke($type, 'search', 'search', $keys); In other words, the $op = 'search' phase of hook_search is initiated. The other responsibility of search_data is to theme the results page, either by invoking the hook_search_page implementation for the module doing the search, or by defaulting to theme('search_results').

Despite the fact that the search framework expects modules to do their own searches, it also provides a mechanism for searching the search index (see step #1). The function do_search, in its simplest form, is a breeze to use. Take a list of keywords and specify a type ('node' for searching node content), and get search results like this:

Example 4: Using do_search to find content.

The $results will be an array of top ranking node ids for the keywords "foo" or "bar" or "baz". As this function is one of the core API functions of the search module, you can feel free to call it for your own purposes any time you want. For example, call it from within a block, taking keywords from taxonomy terms or a user's profile interests, and use the returned results as a form of content recommendation.

The full function signature for do_search, however, is quite intimidating:

Example 5: do_search, Search's API function for finding content.

Discussing all the possible values for the parameters is outside the scope of this article, but the plethora of options are there so that calling code can interact with two distinct queries by injecting JOIN and WHERE clauses into each of them. Sorts can be specified as well, although I don't recall ever seeing this feature utilized.

Return formatted results

If you want to utilize the search module's standard formatting for search results, your hook_search('search') has to build a structured array of results where each result follows the format:

Required keys:

• link: The URL of the item.
• type: The translated type, et. "Blog entry".

Optional keys:

• title: The title of the result.
• user: The themed username of the user who created the search result (ie. node author).
• date: The timestamp associated with the search result.
• snippet: An excerpt of text that gives the context of the keywords that were found in the search result. The search module provides a function, search_excerpt(), which can be used to highlight the keywords within this snippet, but you must call it yourself while building the search result.

Conclusion

There are potentially many steps that go into doing a search and displaying the results. The search module provides a framework for managing all of these steps, and an API for accessing the various bits and pieces even outside of the context of a traditional search page. The functions search_excerpt, search_index and do_search, in particular, can be called by modules outside of the traditional hook_search context.