PHP Classes
elePHPant
Icontem

Fuse: Fuzzy search of arrays using the Bitap algorithm

Recommend this page to a friend!
  Info   View files Documentation   View files View files (32)   DownloadInstall with Composer Download .zip   Reputation   Support forum (1)   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2017-11-24 (21 days ago) RSS 2.0 feedNot enough user ratingsTotal: 70 All time: 8,973 This week: 560Up
Version License PHP version Categories
fuse 1.0Custom (specified...5Algorithms, PHP 5, Searching
Description Author

This package can perform fuzzy search of arrays using the Bitap algorithm.

It can take an array of data elements that contain arrays of property values.

It can index data elements by given keys so it can perform search for elements with property values with exact or similar text.

This package is a port of the fuse.js JavaScript library.

Innovation Award
PHP Programming Innovation award nominee
January 2017
Number 18
Fuzzy search allows determining if a text string is similar to another. Bitap is a fuzzy search algorithm.

This package provides a pure PHP implementation of the Bitap algorithm ti match strings in arrays.

Manuel Lemos
Name: AccountKiller <contact>
Classes: 1 package by
Country: ???
Age: ???
All time rank: 4129
Week rank: 922 Up
Innovation award
Innovation award
Nominee: 1x

Details

Fuse

A fuzzy search library for PHP based on the Bitap algorithm

This is a PHP port of the awesome Fuse.js project and provides 100% API compatibility.

> Latest compatible Fuse.js version: 3.2.0

For an approximate demonstration of what this library can do, check out their demo & usage.

Installation

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

composer require loilo/fuse

> Note: Be aware that this package has the same major and minor version as the Fuse.js original. However, the patch version numbers may differ since this repository may need additional fixes from time to time.

Usage

<?php
require_once 'vendor/autoload.php';

$fuse = new \Fuse\Fuse([
  [
    "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"
  ],
], [
  "keys" => [ "title", "author" ],
]);

$fuse->search('hamil');

/*
Array
(
  [0] => Array
    (
      [title] => The Lock Artist
      [author] => Steve Hamilton
    )
  [1] => Array
    (
      [title] => HTML5
      [author] => Remy Sharp
    )
)
*/

Options

keys (type: array)

List of properties that will be searched. This supports nested properties, weighted search, searching in arrays of strings and associative arrays etc:

$books = [
  [
    "title" => "Old Man's War",
    "author" => [
      "firstName" => "John",
      "lastName" => "Scalzi"
    ]
  ]
];
$fuse = new \Fuse\Fuse($books, [
  "keys" => [ "title", "author.firstName" ]
]);

id (type: string)

The name of the identifier property. If specified, the returned result will be a list of the items' identifiers, otherwise it will be a list of the items.

caseSensitive (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: "indices" => [ $start, $end ]. These can consequently be used for highlighting purposes.

shouldSort (type: bool, default: true)

Whether to sort the result list, by score.

getFn (type: function, default: \Fuse\Helpers\deep_value)

The get function to use when fetching an associative array's properties. The default will search nested paths like foo.bar.baz.

/*
 * @param {array|object} $data The object or associative array being searched
 * @param {string}       $path The path to the target property
 */

'getFn' => function ($data, $path) {
    // Example using a ->get() method on objects and simple index access on arrays
    return is_object($data)
        ? $data->get($path)
        : $data[$path];
}

sortFn (type: function, default: sort by score)

The function that is used for sorting the result list.

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.

maxPatternLength (type: int, default: 32)

The maximum length of the search pattern. The longer the pattern, the more intensive the search operation will be. Whenever the pattern exceeds the maxPatternLength, an error will be thrown. Why is this important? Read this#Word_size_choice).

verbose (type: bool, default: false)

Will print out steps. Useful for debugging.

tokenize (type: bool, default: false)

When true, the search algorithm will search individual words and the full string, computing the final score as a function of both. Note that when tokenize is true, the threshold, distance, and location are inconsequential for individual tokens.

tokenSeparator (type: string, default: / +/g)

A regular expression string used to separate words of the search pattern when searching. Only applicable when tokenize is true.

matchAllTokens (type: bool, default: false)

When true, the result set will only include records that match all tokens. Will only work if tokenize is also true.

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.

minMatchCharLength (type: int, default: 1)

When set to include matches, only those whose length exceeds this value will be returned. (For instance, if you want to ignore single character index returns, set to 2)

Methods

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

search($pattern)

/*
@param {string} $pattern The pattern string to fuzzy search on.
@return {array} A list of all search matches.
*/

Searches for all the items whose keys (fuzzy) match the pattern.

setCollection($list)

/*
@param {array}  $list The new data to use
@return {array}       The provided $list
*/

Sets a new list of data for Fuse to match against.

Weighted Search

In some cases you may want certain keys to be weighted differently for more accurate results. You may provide each key with a custom weight (where 0 < weight <= 1):

$fuse = new \Fuse\Fuse($books, [
  "keys" => [
    [
      "name" => "title",
      "weight" => 0.3
    ],
    [
      "name" => "author",
      "weight" => 0.7
    ]
  ]
]);

Contributing

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

Please note that I'm striving for feature parity with the original Fuse.js and therefore won't add own features beyond bug fixes.

  Files folder image Files  
File Role Description
Files folder imagesrc (1 file, 2 directories)
Files folder imagetest (18 files, 1 directory)
Accessible without login Plain text file .editorconfig Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file README.md Doc. Documentation

  Files folder image Files  /  src  
File Role Description
Files folder imageBitap (6 files)
Files folder imageHelpers (2 files)
  Plain text file Fuse.php Class Class source

  Files folder image Files  /  src  /  Bitap  
File Role Description
  Plain text file Bitap.php Class Class source
  Accessible without login Plain text file matched_indices.php Aux. Auxiliary script
  Accessible without login Plain text file pattern_alphabet.php Aux. Auxiliary script
  Accessible without login Plain text file regex_search.php Aux. Auxiliary script
  Accessible without login Plain text file score.php Aux. Auxiliary script
  Accessible without login Plain text file search.php Aux. Auxiliary script

  Files folder image Files  /  src  /  Helpers  
File Role Description
  Accessible without login Plain text file deep_value.php Aux. Auxiliary script
  Accessible without login Plain text file is_list.php Aux. Auxiliary script

  Files folder image Files  /  test  
File Role Description
Files folder imagefixtures (1 file)
  Plain text file BookTest.php Class Class source
  Plain text file ExactMatchTest.php Class Class source
  Plain text file FruitTest.php Class Class source
  Plain text file IdNumberTest.php Class Class source
  Plain text file IncludeScoreTest.php Class Class source
  Plain text file LongPatternTest.php Class Class source
  Plain text file OptionsTest.php Class Class source
  Plain text file RecurseArraysTest.php Class Class source
  Plain text file RecurseIntoArrayObjectsTest.php Class Class source
  Plain text file SearchIdTest.php Class Class source
  Plain text file SearchListTest.php Class Class source
  Plain text file SearchLocationTest.php Class Class source
  Plain text file SearchNestedIdTest.php Class Class source
  Plain text file SetListTest.php Class Class source
  Plain text file TokenTest.php Class Class source
  Plain text file UseIdIncludeScoreTest.php Class Class source
  Plain text file UseIdTest.php Class Class source
  Plain text file WeightedSearchTest.php Class Class source

  Files folder image Files  /  test  /  fixtures  
File Role Description
  Accessible without login Plain text file books.php Aux. Auxiliary script

 Version Control Unique User Downloads Download Rankings  
 100%
Total:70
This week:0
All time:8,973
This week:560Up
User Comments (1)
nice
9 months ago (muabshir)
70%StarStarStarStar