Search Module Options

The Query Handler

The QueryHandler class is responsible for retrieving, sanitising, and storing the user's query.

Instantiating the QueryHandler

The QueryHandler is instantiated by invoking the getInstance() method on the QueryHandlerFactory. You then need to invoke the handleQuery() method to actual start the process.

Description:

$queryHandler = \T4\PHPSearchLibrary\QueryHandlerFactory::getInstance('QueryHandler', $queryString);

Example:

Example #1 instantiating the query handler

$queryHandler = QueryHandlerFactory::getInstance('QueryHandler', $_SERVER["QUERY_STRING"]);
$queryHandler->handleQuery();

Options

Setting Stop Words

By default the QueryHandler has a built-in list of stop words that will be removed from the user's query. You can provide a custom array of stop words by invoking the setStopWords() method passing in the array.

The words in the array must follow a specific syntax. For each word it must start with /\b and end with \b/is with the word in between.

Description/Parameters

$queryHandler->setStopWords( $stopWords )

Example

$stopWords = array('/\band\b/is', '/\bof\b/is', '/\bin\b/is', '/\bor\b/is', '/\bwith\b/is', '/\bthe\b/is', '/\bat\b/is')
$queryHandler = QueryHandlerFactory::getInstance('QueryHandler', $_SERVER["QUERY_STRING"]);
$queryHandler->setStopWords($stopWords);
$queryHandler->handleQuery();

Stopping Stop Words being Applied

It can be useful in some cases where you don't want stop words to be removed from specific queries, an example of this would be department names that contain 'the' or other common stop words. By default 'the' will be stripped out and the results will be incorrect because the department values don't match. In this case you can disable stop word removal for certain GET parameters by invoking the setDontRemoveStopwords() method.

Example

$queryHandler->setDontRemoveStopwords(array('courseDuration', 'courseLocation', 'courseFaculties', 'courseDepartments','courseType'));

Stopping Tokenization

By default the QueryHandler will tokenize the queries that come in using spaces as the delimiter. There may be occassions where some GET parameters shouldn't be tokenized. For example, a facet that is listing the levels of courses ('Undergraduate Courses', 'Postgraduate Courses'). In this case, if we tokenized these values results would be returned for 'Undergraduate' and 'Courses' thereby including results we don't want. By setting the GET parameter for these to not be tokenzed we're forcing results which have 'Undergraduate Courses' as a phrase to be returned.

Description/Parameters

$queryHandler->setDontTokenize( $dontTokenize)

Example

$dontTokenize = array('courseLevel'); 
$queryHandler = QueryHandlerFactory::getInstance('QueryHandler', $_SERVER["QUERY_STRING"]);
$queryHandler->setDontTokenize($dontTokenize);
$queryHandler->handleQuery();

Stemming Queries

Stemming can be turned on so the root word of the query can be included in the search results e.g. the user searches for management and results are brought back matching management and also the stemmed root manag which should match manage, manager, managing etc.

Description

$queryHandler->stemQuery()

Example

$queryHandler = QueryHandlerFactory::getInstance('QueryHandler', $_SERVER['QUERY_STRING']);
$queryHandler->stemQuery();
$queryHandler->handleQuery();

The stemQuery method must be invoked before the query is handled.

Ignoring Queries

It's sometimes useful for certain GET parameters to not be displayed on the page when showing what the user has searched for. By default both the page and paginate GET parameters are ignored as these are reserved for pagination uses and shouldn't show up as something the user searched for. You can add GET parameters to be ignore by invoking the setIgnoreQueries() method.

Description/Parameters

$queryHandler->setIgnoreQueries( $ignoreQueries );

Example

$ignoredQueries = array('id,page,paginate');
$queryHandler = QueryHandlerFactory::getInstance('QueryHandler', $_SERVER["QUERY_STRING"]);
$queryHandler->setIgnoreQueries($ignoredQueries);
$queryHandler->handleQuery();

Add Special Characters

It's sometimes useful for certain GET parameters can have some special character as brakets or slash that main library doesn't allowed to pass them there is the addCharactersToGenericRegex() method.

Remember to add them in $stopWords = array(..., '/\(/is', '/\)/is'); to be sure that they not be allowed for free input fields.

SECURITY NOTE

Setting characthers such as '<', '>' ,' " ' can create a vunrublity to XSS injection. So make sure to do no use them as a value (in facet lists or dropdown), to prevent any issue related this. This function permits you to set them, no warning will be displayed.

Description/Parameters

$queryHandler->addCharactersToGenericRegex( $chars );

Example

$queryHandler = QueryHandlerFactory::getInstance('QueryHandler', $_SERVER["QUERY_STRING"]);
$queryHandler->addCharactersToGenericRegex(arrau('(',')','-'));
$queryHandler->handleQuery();

Handling the Query

Once all the options have been configured you need to invoke the handleQuery() method.

$queryHandler->handleQuery();

Accessible Methods

There are a number of methods you can use to interact with the QueryHandler.

getQueryArray

Returns the query array.

Description

Array getQueryArray()

getSearchTerms

Returns an array of queries for display purposes. These values don't include any of the queries that are to be ignored.

Array getQueryArray()

getQueryValue

Returns an array of values belonging to the specified query.

Description/Parameters

Array getQueryValue( mixed $key )

Errors/Exceptions

• Throws an OutOfBoundsException if the provided key does not exist.

Example

Example #1 returning the value from the 'keyword' parameter

$chosenCampuses = $queryHandler->getQueryValue('campusLocation');

If the query string was ?keyword=history&campusLocation=dublin&campusLocation=london, chosenCampuses would contain array('dublin', 'london').

isQuerySet

Returns true or false depending on whether the GET parameter was specified in the query or not.

Description/Parameters

Boolean isQuerySet( mixed $key )

Provide the GET parameter that you want to see whether it was used or not.

Example

Example #1 checking if a query was used

if ($queryHandler->isQuerySet('campusLocation')) {
    // some code here
}

doQuerysExist

Check whether any queries have been specified

Description

Boolean doQuerysExist()