• Stars
    star
    320
  • Rank 131,126 (Top 3 %)
  • Language
    PHP
  • License
    Apache License 2.0
  • Created about 8 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

πŸ” Fuzzy search for PHP, ported from Fuse.js

The Fuse logo, a violet asterisk, in reference to the Fuse.js logo

Fuse

A fuzzy search library for PHP

Tests Packagist PHP Version

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

Check out their demo and examples to get a good feel for what this library is capable of.

Latest compatible Fuse.js version: 6.6.2


Table of Contents:


Installation

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.

Usage

Here's a simple usage example:

<?php
require_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's item refers to the matched entry itself and refIndex 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,
    ],
];

Options

Fuse has a lot of options to refine your search:

Basic Options

isCaseSensitive

  • Type: bool
  • Default: false

Indicates whether comparisons should be case sensitive.


includeScore

  • Type: bool
  • Default: false

Whether the score should be included in the result set. A score of 0 indicates a perfect match, while a score of 1 indicates a complete mismatch.


includeMatches

  • Type: bool
  • Default: false

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


minMatchCharLength

  • 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 to 2).


shouldSort

  • Type: bool
  • Default: true

Whether to sort the result list, by score.


findAllMatches

  • 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.


keys

  • Type: array
  • Default: []

List of keys that will be searched. This supports nested paths, weighted search, searching in arrays of strings and objects.


Fuzzy Matching Options

location

  • Type: int
  • Default: 0

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


threshold

  • Type: float
  • Default: 0.6

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


distance

  • Type: int
  • Default: 100

Determines how close the match must be to the fuzzy location (specified by location). An exact letter match which is distance characters away from the fuzzy location would score as a complete mismatch. A distance of 0 requires the match be at the exact location specified. A distance of 1000 would require a perfect match to be within 800 characters of the location to be found using a threshold of 0.8.


ignoreLocation

  • Type: bool
  • Default: false

When true, search will ignore location and distance, 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 of location, threshold, distance (or ignoreLocation).

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


Advanced Options

useExtendedSearch

  • Type: bool
  • Default: false

When true, it enables the use of unix-like search commands. See example.


getFn

  • 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.


sortFn

  • Type: callable
  • Default: source

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


ignoreFieldNorm

  • Type: bool
  • Default: false

When true, the calculation for the relevance score (used for sorting) will ignore the field-length norm.


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

fieldNormWeight

  • Type: float
  • Default: 1

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


Global Config

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

// Get an associative array of all options listed above
Fuse::config();

// Merge associative array of options into default config
Fuse::config(['shouldSort' => false]);

// Get single default option
Fuse::config('shouldSort');

// Set single default option
Fuse::config('shouldSort', false);

Methods

The following methods are available on each Fuse\Fuse instance:


search

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

public function search(mixed $pattern, ?array $options): array

The $pattern can be one of:

The $options:

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

setCollection

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

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

Example:

$fruits = ['apple', 'orange'];
$fuse = new Fuse($fruits);

$fuse->setCollection(['banana', 'pear']);

add

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

public function add(mixed $doc): void

Example:

$fruits = ['apple', 'orange'];
$fuse = new Fuse($fruits);

$fuse->add('banana');

sizeof($fruits); // => 3

remove

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).

public function remove(?callable $predicate): array

Example:

$fruits = ['apple', 'orange', 'banana', 'pear'];
$fuse = new Fuse($fruits);

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

removeAt

Removes the doc at the specified index.

public function removeAt(int $index): void

Example:

$fruits = ['apple', 'orange', 'banana', 'pear'];
$fuse = new Fuse($fruits);

$fuse->removeAt(1);

$fuse->getCollection(); // => ['apple', 'banana', 'pear']

getIndex

Returns the generated Fuse index.

public function getIndex(): \Fuse\Core\FuseIndex

Example:

$fruits = ['apple', 'orange', 'banana', 'pear'];
$fuse = new Fuse($fruits);

$fuse->getIndex()->size(); // => 4

Indexing

The following methods are available on each Fuse\Fuse instance:


Fuse::createIndex

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.

public static function 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 = new Fuse($list, $options, $myIndex);

Fuse::parseIndex

Parses a JSON-serialized Fuse index.

public static function 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 it
file_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 = new Fuse($list, $options, $myIndex);

Differences with Fuse.js

Β  Fuse.js PHP Fuse
Get Fuse Version Fuse.version –
Access global configuration Fuse.config property Fuse::config method
List modification Using fuse.add() etc. modifies the original list passed to the new Fuse constructor. In PHP, arrays are a primitive data type, which means that your original list is never modified by Fuse. To receive the current list after adding/removing items, the $fuse->getCollection() method can be used.

Development

Project Scope

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 are not obviously bugs in this PHP port, and you happen to know JavaScript, please check if your use case works correctly in the online demo of Fuse.js as that is the canonical Fuse implementation. If the issue appears there as well, please open an issue in their repo.

Setup

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

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

Clone the repository and cd into it:

git clone https://github.com/loilo/fuse.git
cd 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

Quality Assurance

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:

Command Purpose Description
vendor/bin/phpcs check code style Run PHP_CodeSniffer to verify that the Fuse source code abides by the PSR-12 coding style.
vendor/bin/psalm static analysis Run Psalm against the codebase to avoid type-related errors and unsafe coding patterns.
vendor/bin/phpunit check program logic Run all PHPUnit tests from the test folder.

Contributing

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

More Repositories

1

color-blend

🎨 Blends RGBA colors with various blend modes in JavaScript
TypeScript
123
star
2

auto-group-tabs

Google Chrome extension to automatically group tabs by URL
JavaScript
99
star
3

branchy

πŸƒ Execute a Node.js function in a separate process
JavaScript
93
star
4

vscode-snazzy-light

🍭 A vivid light VS Code color theme
JavaScript
35
star
5

Lowlight

πŸ›‹οΈ Show syntax-highlighted code of 150+ languages in your terminal
PHP
21
star
6

node-symfony-style-console

🎼 Use the style and utilities of the Symfony Console in Node.js
TypeScript
19
star
7

diffr

πŸ’Ž Create and share diffs with Diffr, the privacy focused online text diffing tool.
Vue
18
star
8

livy

πŸ“œ A Monolog-inspired logging library for Node.js
JavaScript
17
star
9

ico2png-cli

πŸ–Ό Batch extract PNG images out of ICO files from the command line
JavaScript
10
star
10

yufka

🌯 Transform JavaScript ASTs the easy way
TypeScript
9
star
11

prettier-php-playground

πŸ’„ A playground for the Prettier PHP plugin
Vue
7
star
12

windows-titlebar-color

πŸ– Node.js package to get the title bar color from Windows 7, 8, 8.1 or 10
JavaScript
6
star
13

node-js-php-data

Convert simple JS data to PHP
JavaScript
6
star
14

node-bash-minifier

Minify bash scripts
JavaScript
6
star
15

node-sass-yaml-importer

Allows importing YAML in Sass files parsed by node-sass.
JavaScript
5
star
16

node-path

πŸ›£ The Node.js `path` module, ported to PHP
PHP
5
star
17

node-html-api

Makes creating an HTML API a breeze
JavaScript
5
star
18

composite-symbol

✳️ Map a series of values to a unique JavaScript Symbol
JavaScript
5
star
19

gfm-preview

Simple preview for GitHub Flavored Markdown
CSS
4
star
20

php-arena

πŸ₯Š A tiny playground for tinkering with PHP snippets in the browser
TypeScript
4
star
21

gyros

πŸ₯™ Transform PHP ASTs the easy way
TypeScript
4
star
22

rx

A template tag for creating regular expressions
TypeScript
3
star
23

find-up

πŸ“ Find a file by walking up ancestor directories
PHP
3
star
24

auto-collapse-tab-groups

Google Chrome extension to automatically collapse unfocused tab groups
TypeScript
3
star
25

node-sass-js-importer

JavaScript
2
star
26

node-php-date

⏰ Use PHP's date() function in JavaScript
JavaScript
2
star
27

completarr

Zero config autocompletions for yargs apps (bash, zsh, fish)
JavaScript
2
star
28

computed-properties

A data store with support for computed properties
TypeScript
2
star
29

native-open

Open a file/URL/app from inside PHP, cross-platform
PHP
2
star
30

blackscreen

A click-to-fullscreen blackscreen PWA
HTML
2
star
31

storage-paths

πŸ—„ Get OS-specific paths for storing your project's config, cache, logs etc.
PHP
1
star
32

monomitter

πŸ“‘ A tiny, overly simplistic event bus
JavaScript
1
star
33

faction

A single-user private Composer repository
PHP
1
star
34

contao-exec-bundle

πŸ’² Execute Contao-related PHP code directly from the console
PHP
1
star
35

mastodon-bio-rss-crawler

Node.js tool for extracting websites/feeds from your Mastodon follows
JavaScript
1
star
36

sassed

πŸ‘“ A simple editor to compile Sass code in your browser
TypeScript
1
star
37

x-filesystem

πŸ“„ An extension to Symfony's Filesystem Component, able to read and write PHP/YAML/JSON/CSV files
PHP
1
star
38

simple-config

βš™οΈ Simple persistent configuration for your app or module
PHP
1
star
39

vue-browser-state

🌐 Various browser-related implementations for vue-reactivator
JavaScript
1
star
40

Collection

An extended version of Laravel Collections
PHP
1
star
41

vue-reactivator

Create reactive Vue properties from arbitrary global state
JavaScript
1
star