Download the PHP package xenos/asklucy without Composer

AskLucy – A PHP Library for Creating Lucene Search Queries

This project contains an easy to use PHP library for creating Lucene search queries.

Contents

• Installation
  • Install with Git
  • Install with Composer
• Usage
  • Creating Clauses
    • Creating a Term
    • Creating a Phrase
    • Creating a Range
    • Creating a Complex Query
  • Fields
    • Setting a Field to a Term
    • Setting a Field to a Phrase
    • Setting a Field to a Range
    • Setting Fields in Complex Queries
  • Operators
    • Setting an Operator to a Term
    • Setting an Operator to a Phrase
    • Setting an Operator to a Range
    • Setting Operators in Complex Queries
  • Relevance Boosting
  • Fuzziness
  • Proximity Search
  • Range Search

Installation

Install with Git

Install with Composer

This project is available at Packagist: https://packagist.org/packages/xenos/asklucy

You can install it with the following command:

Usage

This library contains classes providing a __toString() method. By casting their instances with the (string) operator you will get clauses ready to use for Lucene search engine. For more details about the syntax of Lucene search queries you may read the official docs. But the following sections will give you all necessary information about building such queries.

A query to Lucene search engine consists of one ore more clauses for matching documents. There are four types of clauses:

1. Terms matching documents that contain a single word.
2. Phrases matching documents that contain a sequence of words.
3. Ranges matching documents that contain a value between a lower and an upper bound.
4. Complex queries containing one or more sub-clauses of any type.

Creating Clauses

Creating a Term

To create a query matching documents that contain a single word, e. g. "word", just build a new as follows:

The string representation of the query will be:

word

Creating a Phrase

To create a clause matching documents that contain a sequence of words, e. g. "Lucene search", you can instantiate a new with the following snippet:

The string representation of the query will be:

"Lucene query"

Creating a Range

To create a range matching documents that contain a value between a lower and an upper bound, instantiate a new with the bounds:

The string representation of the query will be:

[alpha TO omega]

Creating a Complex Query

To create a complex query containing one or more clauses of any type, instantiate a new and add clauses:

The string representation of the query will be:

word "Lucene query"

Fields

For all types of clauses you can specify a field to search in by calling the method or by adding an additional parameter to the factory method.

Setting a Field to a Term

To search for documents containing "Lucene" in the (field named) "title", use the following snippet:

As a shortcut you may also set the field directly by adding a second parameter to the factory:

Both lead to the same result:

title:Lucene

Setting a Field to a Phrase

You can specify a field to search in by calling the method ...

... or you can set the field by adding a second parameter to the factory:

The result is the same:

title:"Search Engine"

Setting a Field to a Range

Specify a field to search the value range in by calling the method ...

... or set the field by adding a third parameter to the factory:

The result is the same:

name:[Anna TO Dora]

Setting Fields in Complex Queries

As before you can specify a search field by calling the method ...

... or by passing a parameter to the factory:

In both cases the string representation of the query will be:

title:(Lucene Apache)

Note, that the brackets are set automatically, if more than one sub-clauses were set. If you want to specify a field just for a certain sub-clause, you may do this:

The result will be:

title:Lucene Apache

Operators

For all types of clauses you can add operators to define, if matching is required, prohibited or optional. Just call , , or . Note, that a clause is optional by default, so that calling is optional. But it can be used to override an operator set before.

Setting an Operator to a Term

To require the word "PHP" necessarily, use the following snippet...

... and get:

+PHP

To prohibit the word "Java", do this...

... and you'll get that:

-Java

Setting an Operator to a Phrase

You can add operators to phrases in the same manner as to terms.

Require a phrase necessarily...

... and get the string representation:

+"Lucene query"

Prohibit the phrase...

... and get:

-"Java development"

Setting an Operator to a Range

Adding operators to ranges works in the same way as adding them to the other kinds of clauses.

Require a value of a range necessarily...

... and get the string representation:

+[Anna TO Doro]

Prohibit a value of the range...

... and get:

-[Anna TO Doro]

Setting Operators in Complex Queries

You can add operators to complex queries right as to terms and phrases:

The query will match all documents containing necessarily "Lucene" or "search query" (or both). The string representation will be:

+(Lucene "search query")

Instead of creating sub-clauses, setting operators to them and finally adding them to a complex query, you can use , or , what automatically sets the "optional", "required" or "prohibited" operator to the given sub-queries.

The string representation of the query will be:

word +"Lucene query" -"Java development"

Relevance Boosting

You can add a "boost" to a clause of any type, to make it more relevant. Just call with a boost factor greater than zero.

The result will be:

Apache Lucene^2.5 "search engine"^2

Fuzziness

You can do a fuzzy search term by calling :

The string representation of the query will be:

word~

The fuzzy search is based on Damerau-Levenshtein Distance, that is the number of single character edits allowed to reach the search term. By using the optional parameter, you can define that distance:

The string representation of the query will be:

word~1

The query will also match terms like "Ford", that can be reached by edit a single character of the search term. The default value of is 2, so that also words like "nerd" will be matched. By using 0 as parameter, fuzzy search is disabled, what is the same as just don't calling . Allowed values are 0, 1 and 2.

Proximity Search

You can specify a maximum distance to find terms, that are near each other in a document. For example, if you search for the terms "search" and "term" within five words, create the following phrase:

The string representation of the query will be:

"search term"~5

The proximity 0 means exact matching and, as the Lucene default value, must not be rendered. The proximity 1 would allow interchanging words, "term search".

Range Search

Ranges matching documents that contain a value between a lower and an upper bound. They can be inclusive or exclusive of the bounds.

This clause matches documents that contain values between "Alpha" and "Omega" inclusive "Alpha" and "Omega". The clause will be rendered with square brackets.

[Alpha TO Omega]

Note, that ranges are inclusive by default, so that you don't have to call . You can make the range exclusive of the bounds by calling :

The clause will be rendered with curly brackets:

{Alpha TO Omega}