Download the PHP package futape/search without Composer
On this page you can find all versions of the php package futape/search. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download futape/search
More information about futape/search
Files in futape/search
Package search
Short Description An easy to use and extendable search framework
License MIT
Informations about the package search
futape/search
This framework offers a basic set of utilities for building your search index and search it using various customizable matching strategies.
You are completely free in the choice and the structure of the objects to index.
New matchers can be implemented and added in seconds. The same applies to highlighters.
Install
Architecture
Matchers & Values
Matchers are components for matching an indexed value against a search term. The type of the value and of the search
term is technically completely free. However, different concrete matchers may specify or force a type.
A matcher class always goes along with a value class, being the class, and the only class, whose instances the matcher
can work with. A value instance in turn contains the real value, the matcher matches against. Again, the type of that
value is technically undefined, however a value may specify or force one.
Besides the managed value, a value instance also manages a matching score, as well as a highlighted version of the
managed value.
Every value has a highlighter attached to it. By default it's initialized with a DummyHighlighter
. As soon as a
searchable is added to the Index
, the index's highlighter (HtmlHighlighter
by default) is forwarded to all values
provided by the searchable.
Please note, a value instance is intended to be provided by exactly one searchable at a time and is not shared by
multiple searchables. Otherwise you may encounter undefined behavior.
There are an abstract matcher and value you can extend to build your own, as well as a few predefined concrete
matchers. There's also a AbstractArrayValue
and a AbstractStringValue
class which extend the AbstractValue
class
and manages the managed value to be an array or string respectively.
Token Matcher
The TokenMatcher
works with TokenValue
, which manages a 1-dim string array of strings.
The managed array is searched strictly for a given search term. The score is increased by 1 for every match and the
matching value is highlighted.
Filename Matcher
The FilenameMatcher
works with FilenameValue
, which manages a path as a string.
The basename of the path is compared strictly to the search term. If that fails, the matcher tries to match the filename
of the path, which requires the path not to end with a slash or to point to a directory. If any attempt matches, the
score is increased by 1 and the matching part is highlighted.
Fulltext Matcher
The FulltextMatcher
works with FulltextValue
, which manages any arbitrary string.
Searches the string for the search term. The areas the term can exist in are configured using
setWordBoundarySeverity()
. The available WORD_BOUNDARY_SEVERITY_*
constants are documented below:
WORD_BOUNDARY_SEVERITY_EXTRA_HIGH
: Term has to be surrounded by whitespacesWORD_BOUNDARY_SEVERITY_HIGH
: Term has to be surrounded by any non-alphanumeric character (including "_")WORD_BOUNDARY_SEVERITY_MEDIUM
(default): LikeWORD_BOUNDARY_SEVERITY_HIGH
, but a non-digit following a digit (or vice versa) also marks a term boundaryWORD_BOUNDARY_SEVERITY_LOW
: No rules at all. The term can exist anywhere in the search value.
If found, the score is increased by the number of found occurrences of the term, but also by considering the term's complexity (i.e. its length/number of words in it).
Building Your Own Matcher
To create your own matcher, just create one class extending the AbstractMatcher
class and one extending the
AbstractValue
class. Then set the SUPPORTED_VALUE
constant of your matcher class to the FQCN of your value class.
In your matcher class, you have to implement the matchValue
method which takes the value managed by an instance of
your value class, the search term and a highlighter instance, as well as references to the highlighted value and the
matching score.
Your value has to implement the resetHighlighted
method which takes a copy of the value managed by the value instance,
which will become the highlighted value, resets it to its initial state and returns it. Most often this means to
lowlight it using the lowlight
method of the value's highlighter.
To implement a matcher that just compares the value to the term, highlights that value if it matches and increases the score, you may create a class like below:
EqualsMatcher.php
EqualsValue.php
Highlighters
Highlighters are used to highlight matching values, as well as for lowlighting values (i.e. process the value
according to the highlighter's logic and character but don't highlight it).
Technically a highlighter may highlight any value, being it a scalar value like a string or a float, or something like
an object. It doesn't know about the type of the value it should handle and every highlighter behaves differently and
implements its own way of highlighting values and has a different return value. The only exception from this rule is the
HighlighterInterface::highlightAreas()
method which always expects a string argument.
A string highlighter for example tries to highlight the value as a string and fails if the value can't be converted to
one. Other highlighters may not convert the value at all and just wrap them into a special "highlighted" object.
There are a few predefined highlighters as well as an abstract one and an interface to built you own
highlighters.
String Highlighters
String highlighters are made for highlighting strings.
There are two predefined string highlighters:
PlainHighlighter
: Highlights a value in a markdown-like manner for usage in plaintext (e.g.**Foo** Bar
)HtmlHighlighter
: Highlights a value using HTMLmark
tags (e.g.<mark>Foo</mark> Bar
) and HTML-escapes special characters
Dummy Highlighter
The DummyHighlighter
exists just to have a highlighter that implements the HighlighterInterface
, but doesn't have
any functionality. It just returns the value as it comes in.
Building Your Own Highlighter
To build your own highlighter, you may either create it from scratch by implementing the HighlighterInterface
or
by extending the AbstractStringHighlighter
.
Latter is an abstract class for creating string highlighters. The only thing you have to do it to define one string that
starts a highlighted part and one that ends it.
YellHighlighter.php
When writing your own HighlighterInterface::highlightAreas()
implementation, you may want to use the
HighlighterHelper::processAreas()
method which normalizes and validates the areas array.
Indexed Objects (Searchables)
These are the objects in the index you can search through.
Because the source of the data to match against is completely unknown to this framework and is domain to your
application, there aren't any concrete classes to build indexed objects.
Instead you have to create your own Searchables.
Searchables are objects that provide various value objects containing the data of some entity. How these data is
retrieved is completely up to you.
When the index is searched, the value objects are passed to matchers supporting these value objects, and are compared
against the search term by them.
To create your own searchable, you may either implement the SearchableInterface
or extend the AbstractSearchable
class.
When extending the AbstractSearchable
, the only method to implement is initMatcherValues
, which is called by the
constructor and should populate the matcher values by calling the registerMatcherValue
method. You may do something
like below.
Again, you are completely free about the source of the data. Instead of passing a model instance to the constructor like in the example above, you may pass just a value (or even nothing) and do some API calls or anything else you can imagine.
Usage
Testing
The library is tested by unit tests using PHP Unit.
To execute the tests, install the composer dependencies (including the dev-dependencies), switch into the tests
directory and run the following command:
All versions of search with dependencies
ext-mbstring Version *
futape/filesystem-utility Version ^1.2.0
futape/string-utility Version ^1.0.0
futape/array-utility Version ^2.0.0