{"id":18237613,"url":"https://github.com/xenoseleatikos/asklucy","last_synced_at":"2025-10-30T05:15:09.759Z","repository":{"id":57083671,"uuid":"88522040","full_name":"XenosEleatikos/AskLucy","owner":"XenosEleatikos","description":"A PHP Library for Creating Lucene Search Queries","archived":false,"fork":false,"pushed_at":"2019-03-17T17:40:53.000Z","size":1269,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-20T05:02:14.381Z","etag":null,"topics":["lucene","php","query","search"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/XenosEleatikos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-17T15:29:06.000Z","updated_at":"2024-11-16T16:53:37.000Z","dependencies_parsed_at":"2022-08-24T14:56:39.953Z","dependency_job_id":null,"html_url":"https://github.com/XenosEleatikos/AskLucy","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XenosEleatikos%2FAskLucy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XenosEleatikos%2FAskLucy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XenosEleatikos%2FAskLucy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XenosEleatikos%2FAskLucy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XenosEleatikos","download_url":"https://codeload.github.com/XenosEleatikos/AskLucy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247134992,"owners_count":20889412,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lucene","php","query","search"],"created_at":"2024-11-05T02:42:17.145Z","updated_at":"2025-10-30T05:15:04.702Z","avatar_url":"https://github.com/XenosEleatikos.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/XenosEleatikos/AskLucy.svg)](https://travis-ci.org/XenosEleatikos/AskLucy)\n\n# AskLucy – A PHP Library for Creating Lucene Search Queries\nThis project contains an easy to use PHP library for creating Lucene search queries.\n\n## Contents\n- [Installation](#installation)\n    - [Install with Git](#install-with-git)\n    - [Install with Composer](#install-with-composer)\n- [Usage](#usage)\n    - [Creating Clauses](#creating-clauses)\n        - [Creating a Term](#creating-a-term)\n        - [Creating a Phrase](#creating-a-phrase)\n        - [Creating a Range](#creating-a-range)\n        - [Creating a Complex Query](#creating-a-complex-query)\n    - [Fields](#fields)\n        - [Setting a Field to a Term](#setting-a-field-to-a-term)\n        - [Setting a Field to a Phrase](#setting-a-field-to-a-phrase)\n        - [Setting a Field to a Range](#setting-a-field-to-a-range)\n        - [Setting Fields in Complex Queries](#setting-fields-in-complex-queries)\n    - [Operators](#operators)\n        - [Setting an Operator to a Term](#setting-an-operator-to-a-term)\n        - [Setting an Operator to a Phrase](#setting-an-operator-to-a-phrase)\n        - [Setting an Operator to a Range](#setting-an-operator-to-a-range)\n        - [Setting Operators in Complex Queries](#setting-operators-in-complex-queries)\n    - [Relevance Boosting](#relevance-boosting)\n    - [Fuzziness](#fuzziness)\n    - [Proximity Search](#proximity-search)\n    - [Range Search](#range-search)\n\n## Installation\n### Install with Git\n```bash\ngit clone https://github.com/XenosEleatikos/AskLucy.git\n```\n\n### Install with Composer\nThis project is available at [Packagist](https://packagist.org): https://packagist.org/packages/xenos/asklucy\n\nYou can install it with the following command:\n```bash\ncomposer require xenos/asklucy\n```\n\n## Usage\nThis library contains classes providing a ``__toString()`` method. By casting their instances with the ``(string)``\noperator you will get clauses ready to use for Lucene search engine. For more details about the syntax of Lucene search\nqueries you may [read the official docs](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html). But the following\nsections will give you all necessary information about building\nsuch queries.\n\nA query to Lucene search engine consists of one ore more clauses for matching documents. There are four types of clauses:\n1. Terms matching documents that contain a single word.\n2. Phrases matching documents that contain a sequence of words.\n3. Ranges matching documents that contain a value between a lower and an upper bound.\n4. Complex queries containing one or more sub-clauses of any type.\n\n### Creating Clauses\n#### Creating a Term\nTo create a query matching documents that contain a single word, e. g. \"word\", just build a new ```Term``` as follows:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$term = Lucene::term('word');\n```\nThe string representation of the query will be:\n\n\u003e word\n\n#### Creating a Phrase\nTo create a clause matching documents that contain a sequence of words, e. g. \"Lucene search\", you can instantiate a new\n```Phrase``` with the following snippet:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$phrase = Lucene::phrase('Lucene query');\n```\n\nThe string representation of the query will be:\n\n\u003e \"Lucene query\"\n\n#### Creating a Range\nTo create a range matching documents that contain a value between a lower and an upper bound, instantiate a new\n```Rage``` with the bounds:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$range = Lucene::range('alpha', 'omega');\n```\n\nThe string representation of the query will be:\n\n\u003e [alpha TO omega]\n\n#### Creating a Complex Query\nTo create a complex query containing one or more clauses of any type, instantiate a new ```Query``` and add clauses:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$phrase = Lucene::query()\n    -\u003eadd(Lucene::term('word'))\n    -\u003eadd(Lucene::phrase('Lucene query'));\n```\n\nThe string representation of the query will be:\n\n\u003e word \"Lucene query\"\n\n### Fields\nFor all types of clauses you can specify a field to search in by calling the method ```setField()``` or by adding an\nadditional parameter to the factory method.\n\n#### Setting a Field to a Term\nTo search for documents containing \"Lucene\" in the (field named) \"title\", use the following snippet:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$term = Lucene::term('Lucene');\n$term-\u003esetField('title');\n```\n\nAs a shortcut you may also set the field directly by adding a second parameter to the factory:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$term = Lucene::term('Lucene', 'title');\n```\n\nBoth lead to the same result:\n\n\u003e title:Lucene\n\n#### Setting a Field to a Phrase\nYou can specify a field to search in by calling the method ```setField()```...\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$phrase = Lucene::phrase('Search Engine');\n$phrase-\u003esetField('title');\n```\n\n... or you can set the field by adding a second parameter to the factory:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$phrase = Lucene::phrase('Search Engine', 'title');\n```\n\nThe result is the same:\n\n\u003e title:\"Search Engine\"\n\n#### Setting a Field to a Range\nSpecify a field to search the value range in by calling the method ```setField()```...\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$range = Lucene::range('Anna', 'Doro');\n$range-\u003esetField('name');\n```\n\n... or set the field by adding a third parameter to the factory:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$range = Lucene::range('Anna', 'Doro', 'name');\n```\n\nThe result is the same:\n\n\u003e name:[Anna TO Dora]\n\n#### Setting Fields in Complex Queries\nAs before you can specify a search field by calling the method ```setField()```...\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$query = Lucene::query()\n    -\u003eadd(Lucene::term('Lucene'))\n    -\u003eadd(Lucene::term('Apache'));\n$query-\u003esetField('title');\n```\n\n... or by passing a parameter to the factory:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$query = Lucene::query('title')\n    -\u003eadd(Lucene::term('Lucene'))\n    -\u003eadd(Lucene::term('Apache'));\n```\n\nIn both cases the string representation of the query will be:\n\n\u003e title:(Lucene Apache)\n\nNote, that the brackets are set automatically, if more than one sub-clauses were set. If you want to specify a field\njust for a certain sub-clause, you may do this:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$query = Lucene::query()\n    -\u003eadd(Lucene::term('Lucene', 'title'))\n    -\u003eadd(Lucene::term('Apache'));\n```\n\nThe result will be:\n\n\u003e title:Lucene Apache\n\n### Operators\nFor all types of clauses you can add operators to define, if matching is required, prohibited or optional. Just call\n```required()```, ```prohibited()```, or ```optional()```. Note, that a clause is optional by default, so that calling\n```optional()``` is optional. But it can be used to override an operator set before.\n\n#### Setting an Operator to a Term\nTo require the word \"PHP\" necessarily, use the following snippet...\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$term = Lucene::term('PHP')\n    -\u003erequired();\n```\n\n... and get:\n\n\u003e +PHP\n\nTo prohibit the word \"Java\", do this...\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$term = Lucene::term('Java')\n    -\u003eprohibited();\n```\n\n... and you'll get that:\n\n\u003e -Java\n\n#### Setting an Operator to a Phrase\nYou can add operators to phrases in the same manner as to terms.\n\nRequire a phrase necessarily...\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$phrase = Lucene::phrase('Lucene query')\n    -\u003erequired();\n```\n\n... and get the string representation:\n\n\u003e +\"Lucene query\"\n\nProhibit the phrase...\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$phrase = Lucene::phrase('Java development')\n    -\u003eprohibited();\n```\n\n... and get:\n\n\u003e -\"Java development\"\n\n#### Setting an Operator to a Range\nAdding operators to ranges works in the same way as adding them to the other kinds of clauses.\n\nRequire a value of a range necessarily...\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$range = Lucene::range('Anna', 'Doro')\n    -\u003erequired();\n```\n\n... and get the string representation:\n\n\u003e +[Anna TO Doro]\n\nProhibit a value of the range...\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$range = Lucene::range('Anna', 'Doro')\n    -\u003eprohibited();\n```\n\n... and get:\n\n\u003e -[Anna TO Doro]\n\n#### Setting Operators in Complex Queries\nYou can add operators to complex queries right as to terms and phrases:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$phrase = Lucene::query()\n    -\u003eadd(Lucene::term('Lucene'))\n    -\u003eadd(Lucene::phrase('search query'))\n    -\u003erequired();\n```\n\nThe query will match all documents containing necessarily \"Lucene\" or \"search query\" (or both). The string representation will\nbe:\n\n\u003e +(Lucene \"search query\")\n\nInstead of creating sub-clauses, setting operators to them and finally adding them to a complex query, you can use\n```Query::shouldHave()```, ```Query::mustHave()``` or ```Query::mustNotHave()```, what automatically sets the \"optional\",\n\"required\" or \"prohibited\" operator to the given sub-queries.\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$query = Lucene::query()\n    -\u003eshouldHave(Lucene::term('word'))\n    -\u003emustHave(Lucene::phrase('Lucene query'))\n    -\u003emustNotHave(Lucene::phrase('Java development'));\n```\n\nThe string representation of the query will be:\n\n\u003e word +\"Lucene query\" -\"Java development\"\n\n### Relevance Boosting\nYou can add a \"boost\" to a clause of any type, to make it more relevant. Just call ```boost()``` with a boost factor\ngreater than zero.\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$term = Lucene::term('Lucene');\n$term-\u003eboost(2.5);\n\n$phrase = Lucene::phrase('search engine')\n    -\u003eboost(2);\n\n$query = Lucene::query()\n    -\u003eadd(Lucene::term('Apache'))\n    -\u003eadd($term)\n    -\u003eadd($phrase);\n```\n\nThe result will be:\n\n\u003e Apache Lucene^2.5 \"search engine\"^2\n\n### Fuzziness\n\nYou can do a fuzzy search term by calling ```Term::fuzzify()```:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$term = Lucene::term('word')\n    -\u003efuzzify();\n```\n\nThe string representation of the query will be:\n\n\u003e word~\n\nThe fuzzy search is based on Damerau-Levenshtein Distance, that is the number of single character edits allowed to reach\nthe search term. By using the optional parameter, you can define that distance:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$term = Lucene::term('word')\n    -\u003efuzzify(1);\n```\n\nThe string representation of the query will be:\n\n\u003e word~1\n\nThe query will also match terms like \"Ford\", that can be reached by edit a single character of the search term. The\ndefault value of ```fuzzify()``` is 2, so that also words like \"nerd\" will be matched. By using 0 as parameter, fuzzy search\nis disabled, what is the same as just don't calling ```fuzzify()```. Allowed values are 0, 1 and 2.\n\n### Proximity Search\nYou can specify a maximum distance to find terms, that are near each other in a document. For example, if you search for\nthe terms \"search\" and \"term\" within five words, create the following phrase:  \n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$phrase = Lucene::phrase('search term')\n    -\u003esetProximity(5);\n```\n\nThe string representation of the query will be:\n\n\u003e \"search term\"~5\n\nThe proximity 0 means exact matching and, as the Lucene default value, must not be rendered. The proximity 1 would\nallow interchanging words, \"term search\".\n\n### Range Search\nRanges matching documents that contain a value between a lower and an upper bound. They can be inclusive or exclusive of\nthe bounds.\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$range = Lucene::range('Alpha', 'Omega')\n    -\u003einclusive();\n```\n\nThis clause matches documents that contain values between \"Alpha\" and \"Omega\" inclusive \"Alpha\" and \"Omega\". The clause\nwill be rendered with square brackets.\n\n\u003e [Alpha TO Omega]\n\nNote, that ranges are inclusive by default, so that you don't have to call ```Range::inclusive()```.\nYou can make the range exclusive of the bounds by calling ```Range::exclusive()```:\n\n```php\n\u003c?php\nuse AskLucy\\Lucene;\n\n$range = Lucene::range('Alpha', 'Omega')\n    -\u003eexclusive();\n```\n\nThe clause will be rendered with curly brackets:\n\n\u003e {Alpha TO Omega}\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxenoseleatikos%2Fasklucy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxenoseleatikos%2Fasklucy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxenoseleatikos%2Fasklucy/lists"}