Weave Code
Matcher Laravel Package
loupe/matcher
Loupe Matcher turns search queries and arbitrary text into precise matches: tokenize phrases and negations, normalize locale-specific spelling variants, decompose compound words, calculate match spans, and format results with highlighting, cropping, and truncation.
A library to highlight and crop terms and context within strings such as search results
Frequently asked questions about Matcher
- How do I install loupe/matcher in a Laravel application?
- Run composer require loupe/matcher. There is no service provider auto-discovery, so you should register a small provider or bind the Tokenizer, Matcher, and Formatter in your AppServiceProvider. Make sure the ext-intl extension is present in every environment, including Docker images, or Composer install will fail. The library is framework-agnostic pure PHP, so no Laravel package config is required.
- Does loupe/matcher ship with a Laravel service provider?
- No, no Laravel service provider is included. The integration is typically a short provider that binds a singleton Formatter together with its Tokenizer and Matcher, plus any default FormatterOptions from your config. Because the components are stateless and deterministic aside from instance-scoped memoization, a singleton binding is safe for both HTTP and queue workers. Keep the binding in the application or presentation layer, not in your domain layer.
- What PHP extensions does loupe/matcher require?
- It has a hard dependency on ext-intl, which provides ICU word boundaries and transliteration for diacritic folding. ext-intl is present by default in Laravel Sail, Forge, and Herd environments, but it is missing from bare php:8.x-alpine images. If you deploy on a minimal image, add the intl extension to your Dockerfile before running Composer install.
- Which Laravel and PHP versions are supported by loupe/matcher?
- There is no published PHP or Laravel support matrix, and the package is still pre-1.0. Since it is framework-agnostic, the Laravel version is unlikely to be a blocker, but you should verify it against your own PHP and Laravel matrix in CI. Pin the exact version you test and treat upgrades as potentially behavior-changing.
- How do I highlight search terms in a string with loupe/matcher?
- Create a Tokenizer with a locale configuration such as English, pass it to a Matcher, and wrap that in a Formatter. Build a FormatterOptions value object with withEnableHighlight enabled and optionally withEnableCrop and withCropLength, then call format on the source text with the user query. The result is a string containing the original text with emphasis markup around matches. In Laravel you would typically bind the Formatter once and call it from a snippet or presenter class.
- Is loupe/matcher output safe from XSS?
- The formatter returns raw HTML markup, so your application owns the XSS boundary. This is the most important engineering decision in the integration: escape or sanitize the source text before formatting, and never pass untrusted markup through as highlighted text. Do not output the result with Blade escaped echo, since that would escape your emphasis tags too; instead use a controlled pipeline with an allowlist for the highlight tags or mark the sanitized result as safe. Write explicit tests for hostile inputs and queries.
- Should I use loupe/matcher with Meilisearch or Algolia highlighted results?
- Usually no. Search engines such as Meilisearch, Algolia, and Elasticsearch already return formatted or highlighted fields, so running loupe/matcher on top duplicates CPU work and risks inconsistent markup between engines. The strong fits are when you build snippets yourself, for example with Laravel Scout's database driver, LIKE queries, or TNTSearch, or when you need one consistent snippet format across multiple backends. It is also useful for cropping stored fields that the engine does not return.
- Can loupe/matcher crop and truncate long text around matches?
- Yes, FormatterOptions supports withEnableCrop and withCropLength to crop context around matches, and truncation was added in the 0.2 line. The formatter tokenizes the full source text before cropping, so the cost is proportional to document length even when the visible snippet is short. Benchmark on production-shaped long documents, since version 0.4.1 specifically targets highlighting speed on long texts but publishes no benchmark.
- How does loupe/matcher handle compound words and locale-specific spelling?
- Locale configurations control tokenization and normalization. The English configuration decomposes compounds such as toothbrush into tooth and brush, while the German one normalizes umlauts and sharp s and decomposes words like Zeitungspapier. You can implement LocaleConfigurationInterface for other languages, or use the shipped configurations. This makes it practical to match partial terms in compound-heavy content without custom regex.
- Is loupe/matcher production-ready given it is pre-1.0?
- The README carries an explicit caution about API churn, and release history shows behavioral changes landing in minor releases and internal rewrites in patch releases, including the 0.4.0 cache rework and the 0.4.1 highlighting change. Output remains deterministic and unit-testable for a given input and options, and instance-scoped caching keeps it queue-safe, but the snippet format should be treated as unstable. Pin exact versions, add regression tests around snippet output, and spike against production-shaped content before committing. Watch that any internal cache stays per-instance and bounded for long-running workers.
Weaver
How can I help you explore Laravel packages today?