README

A PHP library for searching text with exact, regular-expression, and similarity-based matching strategies.

Requirements

• PHP 8.3 or later

Installation

Install the library with Composer:

composer require adachsoft/text-search

Usage

Create a search engine with the default matcher configuration and search text using a phrase collection:

<?php

declare(strict_types=1);

use AdachSoft\TextSearch\Collection\PhraseCollection;
use AdachSoft\TextSearch\SearchEngineFactory;

$engine = SearchEngineFactory::createDefault();
$phrases = new PhraseCollection(['search phrase']);

$results = $engine->search(
    'Text containing the search phrase.',
    $phrases,
    'exact',
);

foreach ($results as $result) {
    echo $result->matchedText;
}

Each built-in matcher returns the actual text found in the input as MatchResultVo::$matchedText. The query remains available as phrase, while character and byte offsets, position, context, and an optional similarity score are also included.

SearchEngineFactory::createDefault() registers the following matchers:

• exact — exact text matching
• regex — regular-expression matching
• similarity — similarity-based matching

The factory threshold is a fallback for similarity searches. A request can override it without creating another engine:

use AdachSoft\TextSearch\Value\SearchOptionsVo;

$engine = SearchEngineFactory::createDefault(0.8);
$options = new SearchOptionsVo(similarityThreshold: 0.72);
$results = $engine->search($text, $phrases, 'similarity', $options);

The request threshold takes precedence over the threshold configured in the factory. A threshold must be between 0.0 and 1.0.

Main Components

• SearchEngine — coordinates registered matchers and performs searches.
• SearchEngineFactory — creates a search engine with the default matcher configuration.
• MatcherInterface — defines the matcher contract.
• TokenizerInterface — defines the tokenization contract.
• SimilarityStrategyInterface — defines the similarity calculation contract.
• ContextExtractorInterface — defines match-context extraction.
• PositionResolverInterface — defines match-position resolution.

The library also provides immutable value objects and specialized collections for phrases, tokens, match results, contexts, positions, and search options.

License

This library is released under the MIT License.