Repository files navigation

A fuzzy search library for PHP

This is a PHP port of the awesomeFuse.js project and aims to provide full API compatibility wherever possible.

Check out theirdemo andexamples to get a good feel for what this library is capable of.

Latest compatible Fuse.js version: 7.1.0

Table of Contents:

• Installation
• Usage
• Options
• Methods
• Differences with Fuse.js
• Development

This package is available via Composer. To add it to your project, just run:

composer require loilo/fuse

Note that at least PHP 7.4 is needed to use Fuse. For technical reasons, automatic testing is only run against PHP 8.2+.

Here's a simple usage example:

<?phprequire_once'vendor/autoload.php';$list = [    ['title' =>"Old Man's War",'author' =>'John Scalzi',    ],    ['title' =>'The Lock Artist','author' =>'Steve Hamilton',    ],    ['title' =>'HTML5','author' =>'Remy Sharp',    ],    ['title' =>'Right Ho Jeeves','author' =>'P.D Woodhouse',    ],];$options = ['keys' => ['title','author'],];$fuse =new \Fuse\Fuse($list,$options);$fuse->search('hamil');

This leads to the following results (where each result'sitem refers to the matched entry itself andrefIndex provides the item's position in the original$list):

[    ['item' => ['title' =>'The Lock Artist','author' =>'Steve Hamilton',        ],'refIndex' =>1,    ],    ['item' => ['title' =>'HTML5','author' =>'Remy Sharp',        ],'refIndex' =>2,    ],];

Fuse has a lot of options to refine your search:

• Type:bool
• Default:false

Indicates whether comparisons should be case sensitive.

• Type:bool
• Default:false

Indicates whether comparisons should ignore diacritics (accents).

• Type:bool
• Default:false

Whether the score should be included in the result set. A score of0 indicates a perfect match, while a score of1 indicates a complete mismatch.

• Type:bool
• Default:false

Whether the matches should be included in the result set. Whentrue, each record in the result set will include the indices of the matched characters. These can consequently be used for highlighting purposes.

• Type:int
• Default:1

Only the matches whose length exceeds this value will be returned. (For instance, if you want to ignore single character matches in the result, set it to2).

• Type:bool
• Default:true

Whether to sort the result list, by score.

• Type:bool
• Default:false

When true, the matching function will continue to the end of a search pattern even if a perfect match has already been located in the string.

• Type:array
• Default:[]

List of keys that will be searched. This supports nested paths, weighted search, searching in arrays ofstrings andobjects.

• Type:int
• Default:0

Determines approximately where in the text is the pattern expected to be found.

• Type:float
• Default:0.6

At what point does the match algorithm give up. A threshold of0.0 requires a perfect match (of both letters and location), a threshold of1.0 would match anything.

• Type:int
• Default:100

Determines how close the match must be to the fuzzy location (specified bylocation). An exact letter match which isdistance characters away from the fuzzy location would score as a complete mismatch. Adistance of0 requires the match be at the exactlocation specified. A distance of1000 would require a perfect match to be within800 characters of thelocation to be found using athreshold of0.8.

• Type:bool
• Default:false

Whentrue, search will ignorelocation anddistance, so it won't matter where in the string the pattern appears.

Tip: The default options only search the first 60 characters. This should suffice if it is reasonably expected that the match is within this range. To modify this behavior, set the appropriate combination oflocation,threshold,distance (orignoreLocation).

To better understand how these options work together, read aboutFuse.js' Scoring Theory.

• Type:bool
• Default:false

Whentrue, it enables the use of unix-like search commands. Seeexample.

• Type:callable
• Default:source

The function to use to retrieve an object's value at the provided path. The default will also search nested paths.

• Type:callable
• Default:source

The function to use to sort all the results. The default will sort by ascending relevance score, ascending index.

• Type:bool
• Default:false

Whentrue, the calculation for the relevance score (used for sorting) will ignore thefield-length norm.

Tip: The only time it makes sense to setignoreFieldNorm totrue is when it does not matter how many terms there are, but only that the query term exists.

• Type:float
• Default:1

Determines how much thefield-length norm affects scoring. A value of0 is equivalent to ignoring the field-length norm. A value of0.5 will greatly reduce the effect of field-length norm, while a value of2.0 will greatly increase it.

You can access and manipulate default values of all options above via theconfig method:

// Get an associative array of all options listed aboveFuse::config();// Merge associative array of options into default configFuse::config(['shouldSort' =>false]);// Get single default optionFuse::config('shouldSort');// Set single default optionFuse::config('shouldSort',false);

The following methods are available on eachFuse\Fuse instance:

Searches the entire collection of documents, and returns a list of search results.

publicfunction search(mixed$pattern, ?array$options):array

The$pattern can be one of:

• String
• Path
• Extended query
• Logical query

The$options:

• limit (type:int): Denotes the max number of returned search results.

Set/replace the entire collection of documents. If no index is provided, one will be generated.

publicfunction setCollection(array$docs, ?\Fuse\Core\FuseIndex$index):void

Example:

$fruits = ['apple','orange'];$fuse =newFuse($fruits);$fuse->setCollection(['banana','pear']);

Adds a doc to the collection and update the index accordingly.

publicfunction add(mixed$doc):void

Example:

$fruits = ['apple','orange'];$fuse =newFuse($fruits);$fuse->add('banana');sizeof($fruits);// => 3

Removes all documents from the list which the predicate returns truthy for, and returns an array of the removed docs. The predicate is invoked with two arguments:($doc, $index).

publicfunction remove(?callable$predicate):array

Example:

$fruits = ['apple','orange','banana','pear'];$fuse =newFuse($fruits);$results =$fuse->remove(fn($doc) =>$doc ==='banana' ||$doc ==='pear');sizeof($fuse->getCollection());// => 2$results;// => ['banana', 'pear']

Removes the doc at the specified index.

publicfunction removeAt(int$index):void

Example:

$fruits = ['apple','orange','banana','pear'];$fuse =newFuse($fruits);$fuse->removeAt(1);$fuse->getCollection();// => ['apple', 'banana', 'pear']

Returns the generated Fuse index.

publicfunction getIndex(): \Fuse\Core\FuseIndex

Example:

$fruits = ['apple','orange','banana','pear'];$fuse =newFuse($fruits);$fuse->getIndex()->size();// => 4

The following methods are available on eachFuse\Fuse instance:

Pre-generate the index from the list, and pass it directly into the Fuse instance. If the list is (considerably) large, it speeds up instantiation.

publicstaticfunction createIndex(array$keys,array$docs,array$options = []): \Fuse\Core\FuseIndex

Example:

$list = [ ... ];// See the example from the 'Usage' section$options = ['keys' => ['title','author.firstName' ] ];// Create the Fuse index$myIndex = Fuse::createIndex($options['keys'],$list);// Initialize Fuse with the index$fuse =newFuse($list,$options,$myIndex);

Parses a JSON-serialized Fuse index.

publicstaticfunction parseIndex(array$data,array$options = []): \Fuse\Core\FuseIndex

Example:

// (1) When the data is collected$list = [ ... ];// See the example from the 'Usage' section$options = ['keys' => ['title','author.firstName' ] ];// Create the Fuse index$myIndex = Fuse::createIndex($options['keys'],$list);// Serialize and save itfile_put_contents('fuse-index.json',json_encode($myIndex));// (2) When the search is needed// Load and deserialize index to an array$fuseIndex =json_decode(file_get_contents('fuse-index.json'),true);$myIndex = Fuse::parseIndex($fuseIndex);// Initialize Fuse with the index$fuse =newFuse($list,$options,$myIndex);

Please note that I'm striving for feature parity with Fuse.js and therefore will add neither features nor fixes to the search logic that are not reflected in Fuse.js itself.

If you have any issues with search results that arenot obviously bugs in this PHP port, and you happen to know JavaScript, please check if your use case works correctly in theonline demo of Fuse.js as that is the canonical Fuse implementation. If the issue appears there as well, please open an issuein their repo.

To start development on Fuse, you need git, PHP (≥ 7.4) and Composer.

Since code is formatted usingPrettier, it's also recommended to have Node.js/npm installed as well as using aneditor which supports Prettier formatting.

Clone the repository andcd into it:

git clone https://github.com/loilo/fuse.gitcd fuse

Install Composer dependencies:

composer install

Install npm dependencies (optional but recommended). This is only needed for code formatting as npm dependencies include Prettier plugins used by this project.

npm ci

There are different kinds of code checks in place for this project. All of these are run when a pull request is submitted but can also be run locally:

Before submitting a pull request, please add relevant tests to thetests folder.