Recommend this page to a friend! |
Download .zip |
Info | Documentation | View files (86) | Download .zip | Reputation | Support forum (1) | Blog | Links |
Last Updated | Ratings | Unique User Downloads | Download Rankings | |||||
2023-05-24 (1 month ago) | Not enough user ratings | Total: 106 | All time: 9,619 This week: 257 |
Version | License | PHP version | Categories | |||
fuse 1.0 | Custom (specified... | 5 | Algorithms, PHP 5, Searching |
Description | Author Florian Reuschel Contributor | ||||||||||||||
This package can perform fuzzy search of arrays using the Bitap algorithm. Innovation Award
|
|
<div align="center">
<br>
</div>
_A fuzzy search library for PHP_
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:
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.
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,
],
];
Fuse has a lot of options to refine your search:
isCaseSensitive
Indicates whether comparisons should be case sensitive.
includeScore
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
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
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
Whether to sort the result list, by score.
findAllMatches
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
List of keys that will be searched. This supports nested paths, weighted search, searching in arrays of strings and objects.
location
Determines approximately where in the text is the pattern expected to be found.
threshold
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
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
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.
useExtendedSearch
When true
, it enables the use of unix-like search commands. See example.
getFn
The function to use to retrieve an object's value at the provided path. The default will also search nested paths.
sortFn
The function to use to sort all the results. The default will sort by ascending relevance score, ascending index.
ignoreFieldNorm
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
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.
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);
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
:
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
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);
<!-- prettier-ignore -->
| 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.
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.
> 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
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:
<!-- prettier-ignore -->
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.
Before submitting a pull request, please add relevant tests to the test
folder.
Files |
File | Role | Description | ||
---|---|---|---|---|
.github (1 file, 1 directory) | ||||
.vscode (1 file) | ||||
src (1 file, 6 directories) | ||||
test (3 files, 3 directories) | ||||
.editorconfig | Data | Auxiliary data | ||
.prettierignore | Data | Auxiliary data | ||
.prettierrc | Data | Auxiliary data | ||
composer.json | Data | Auxiliary data | ||
composer.lock | Data | Auxiliary data | ||
fuse.svg | Data | Auxiliary data | ||
LICENSE | Lic. | License text | ||
package-lock.json | Data | Auxiliary data | ||
package.json | Data | Auxiliary data | ||
phpcs.xml | Data | Auxiliary data | ||
phpunit.xml | Data | Auxiliary data | ||
psalm.xml | Data | Auxiliary data | ||
README.md | Doc. | Documentation |
Files | / | src |
Files | / | src | / | Core |
File | Role | Description |
---|---|---|
computeScore.php | Aux. | Auxiliary script |
config.php | Example | Example script |
format.php | Aux. | Auxiliary script |
KeyType.php | Class | Class source |
LogicalOperator.php | Class | Class source |
parse.php | Example | Example script |
Register.php | Class | Class source |
Files | / | src | / | Exception |
File | Role | Description |
---|---|---|
IncorrectSearcherTypeException.php | Class | Class source |
InvalidConfigKeyException.php | Class | Class source |
InvalidKeyWeightValueException.php | Class | Class source |
LogicalSearchInval...ForKeyException.php | Class | Class source |
MissingKeyPropertyException.php | Class | Class source |
PatternLengthTooLargeException.php | Class | Class source |
Files | / | src | / | Search |
File | Role | Description | ||
---|---|---|---|---|
Bitap (6 files) | ||||
Extended (10 files) | ||||
SearchInterface.php | Class | Class source |
Files | / | src | / | Search | / | Bitap |
File | Role | Description |
---|---|---|
BitapSearch.php | Class | Class source |
computeScore.php | Aux. | Auxiliary script |
Constants.php | Class | Class source |
convertMaskToIndices.php | Aux. | Auxiliary script |
createPatternAlphabet.php | Aux. | Auxiliary script |
search.php | Example | Example script |
Files | / | src | / | Search | / | Extended |
File | Role | Description |
---|---|---|
BaseMatch.php | Class | Class source |
ExactMatch.php | Class | Class source |
FuzzyMatch.php | Class | Class source |
IncludeMatch.php | Class | Class source |
InverseExactMatch.php | Class | Class source |
InversePrefixExactMatch.php | Class | Class source |
InverseSuffixExactMatch.php | Class | Class source |
parseQuery.php | Class | Class source |
PrefixExactMatch.php | Class | Class source |
SuffixExactMatch.php | Class | Class source |
Files | / | src | / | Tools |
File | Role | Description |
---|---|---|
FuseIndex.php | Class | Class source |
KeyStore.php | Class | Class source |
Norm.php | Class | Class source |
Files | / | src | / | Transform |
File | Role | Description |
---|---|---|
transformMatches.php | Aux. | Auxiliary script |
transformScore.php | Aux. | Auxiliary script |
Files | / | test |
File | Role | Description | ||
---|---|---|---|---|
fixtures (1 file) | ||||
FuzzySearch (23 files) | ||||
LogicalSearch (4 files) | ||||
ExtendedSearchTest.php | Class | Class source | ||
PhpSpecificTest.php | Class | Class source | ||
ScoringTest.php | Class | Class source |
Files | / | test | / | FuzzySearch |
Files | / | test | / | LogicalSearch |
File | Role | Description |
---|---|---|
NestedConditionsTest.php | Class | Class source |
ParserTest.php | Class | Class source |
SearchTest.php | Class | Class source |
SearchWithDottedKeysTest.php | Class | Class source |
Version Control | Unique User Downloads | Download Rankings | |||||||||||||||
100% |
|
|
User Comments (1) | |||||
|
Applications that use this package |
If you know an application of this package, send a message to the author to add a link here.