README

Cakephp-fuse plugin for CakePHP

This plugin is a simple wrapper behavior around Fuse to implement fuzzy search within any model. Searches can only be performed on strings.

This behavior requires at least PHP 7.1 and can only be used with Cakephp 3.x and 4.x branches.

Cakephp-fuse plugin for CakePHP

Installation

You can install this plugin into your CakePHP application using composer.

The recommended way to install composer packages is:

composer require liqueurdetoile/cakephp-fuse

The plugin itself is only a behavior that can be attached to any model in the initialize method :

$this->addBehavior('Lqdt/CakephpFuse.Fuse');

Behavior can also be attached on-the-fly as it does not require any additional initialize operations.

Usage

Basic usage

The behavior provides a fuse method on the model to get back a configured query. For convenience a custom finder is also available. The two following calls are totally equivalent :

$query = $this->Items->fuse('test');
$query = $this->Items->find('fuse' ['filter' => 'test']);

When providing no additional options or configuration, fuzzy search will be applied to all string fields with default options. Any options accepted by Fuse are available. For instance, to restrict keys and tweak threshold (assuming there's a name field in Items data):

$query = $this->Items->fuse('test', ['keys' => ['name'], 'threshold' => 0.2]);
$query = $this->Items->find('fuse' ['filter' => 'test', 'fuse' => [keys' => ['name'], 'threshold' => 0.2]]);

Persistent configuration

You can set up your model to always use a given persistent configuration set when using fuse. Is some options are also provided on-the-fly, they will be mixed with persistent ones and override the latter when conflicting.

// In the initialize method of the model
$this
  ->addBehavior('Lqdt/CakephpFuse.Fuse')
  ->setSearchableFields(['name'])
  ->setOptions(['threshold' => 0.2]);

// or
$this
  ->addBehavior('Lqdt/CakephpFuse.Fuse')
  ->setOptions([
    'keys' => ['name'],
    'threshold' => 0.2
  ]);

// or
$this->addBehavior('Lqdt/CakephpFuse.Fuse', [
  'keys' => ['name'],
  'threshold' => 0.2
]);

Nested associations

The search can also be done in nested associations (only hasOne or BelongsTo) by using a dot separator with property name :

// Assuming Items belongsTo Owners, with owner as property and name as string field
$query = $this->Items->fuse('test', ['keys' => ['name', 'owner.name']])->contain(['Owners']);

// Assuming Owners also belongsTo Services, with service as property and name as string field
$query = $this->Items->fuse('test', ['keys' => ['name', 'owner.service.name']])->contain(['Owners', 'Owners.Services']);

Autokeys detection

If no keys are provided in options, the model will consider each string field as a searchable key. This also works for any contained model in the query :

// Will search any string fields in Items, Owners and Services
$query = $this->Items->fuse('test')->contain(['Owners', 'Owners.Services']);

API cheatsheet

fuse(string $finder, array $options = [], \Cake\ORM\Query $query = null) : Query

Schedule the fuzzy search with finder keyword(s) on the results of the query and returns the query. If none is provided, the autokeys and default options will be applied only at runtime

find('fuse', array $options = [])

Convenient custom finder that relies on fuse method. To avoid any conflicts between regular query options and fuse options, expected options must follow this convention : ['filter' => <filter>, 'fuse' => [<fuseOption>:<value>, ...]]

getSearchableFields(): array

Returns the persistent defined keys for fuzzy search or populates them with autofields if none is set

setSearchableFields(array $fields = []): self Sets the persistent defined keys for fuzzy search

getFuseOptions(): array

Returns the current persistent options

setFuseOptions(array $options, bool $replace = false): self

Sets the persistent options. If keys are conflicting, provided value will override current value. If replace is set to true, all options will be replaced

There is some more advanced tools that can be found in behavior code.

CHANGELOG

v1.0.2 : Fix find('fuse') documentation
v1.0.1: Add compatibility for cakePHP ^4.2 (getTable deprecation)
v1.0.0: Initial release

liqueurdetoile / cakephp-fuse

Maintainers

Details