Download the PHP package honey-odm/loupe without Composer

🐝 Honey / Loupe

A Honey ODM adapter for Loupe, a Meilisearch-inspired search engine that stores its index in SQLite. There is no server to run, no network round-trip, no separate process to manage — a Loupe index is just a couple of files on disk (or nothing at all, in memory).

The package is a thin translation layer: it turns the ODM's platform-agnostic Criteria into Loupe's SearchParameters / BrowseParameters and filter grammar, and turns Loupe documents back into your objects. It has no persistence logic of its own — Loupe does all the work. It mirrors honey-odm/meilisearch in structure and public surface, so switching backends is mostly a matter of swapping the ObjectManagerFactory.

Features

• 🚀 Modern PHP: Requires PHP 8.4+ with full type safety
• 🗄️ No server required: Loupe stores its index in SQLite, on disk or entirely in memory
• 🏷️ Attribute-based configuration: Use PHP 8 attributes to configure your entities
• 🔍 Flexible querying: The portable Criteria API, or native Loupe SearchParameters / BrowseParameters for what it doesn't model
• 🔄 Property transformers: Built-in transformers for dates, enums, relations, and custom data types
• 📦 Repository pattern: Clean data access layer with repository interfaces
• 🧪 100% test coverage: Thoroughly tested with Pest PHP 💯
• 🧲 Event system: Pre/Post Persist/Update/Remove events

Installation

honey-odm/core has no stable release yet. Composer only honours stability flags declared in the root package, so the @beta carried by this package's own requirement isn't enough — require the core explicitly, as above, or set "minimum-stability": "beta" in your own composer.json.

Quick Start

1. Define your entities

Core attributes (AsDocument, AsField) describe the mapping and are shared across every Honey ODM implementation. Loupe-specific concerns — filterable / sortable / searchable / displayed attributes, and index-wide settings — live in AsAttribute and AsIndex from this package:

The same annotated class works on any other Honey ODM implementation — the #[AsAttribute] / #[AsIndex] flags are simply ignored there.

2. Configure the Object Manager

Before you can persist anything, apply the schema — this creates each collection's data directory and database:

3. Basic operations

4. Persist your data

The Object Manager (not the repository) owns persistence:

The Criteria API

Criteria is the portable, platform-agnostic query builder shared by every Honey ODM implementation. This package compiles it into Loupe's filter grammar and SearchParameters / BrowseParameters objects, throwing rather than silently degrading whenever an expression can't be translated:

Operator support

BETWEEN compiles to the native field BETWEEN l AND r only when both bounds are present, both are inclusive, and both are numeric. Every other shape — an open-ended bound, an exclusive bound, or string bounds — compiles to AND-combined comparisons, which Loupe handles fine (Loupe's own BETWEEN parser accepts floats only; title BETWEEN 'A' AND 'M' is rejected, but title >= 'A' AND title <= 'M' works).

Operators that throw, and why:

• CONTAINS, STARTS_WITH, ENDS_WITH — Loupe has no substring/LIKE operator of any kind.
• EXISTS — Loupe's schema is index-wide: every declared attribute is present on every document, and an undeclared one fails to parse. The operator has no meaningful answer here, and silently returning "always true" would be worse than a clear error.
• A negated WITHIN_GEO_RADIUS / WITHIN_GEO_BOUNDING_BOX (i.e. outsideGeoRadius(), outsideGeoBoundingBox()) — Loupe offers no way to express "outside this radius / box".

Nested paths are not supported

A Loupe index is flat by construction. Attribute names are validated against [a-zA-Z\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*, which has no room for a dot, so createdBy.id is rejected outright:

Meilisearch happily indexes and filters createdBy.id, so a document that needs to be filtered on a nested object cannot be ported to Loupe as-is — the "swap the ObjectManagerFactory and you're done" promise stops there. The core agrees, for what it is worth: AsDocument::getFieldName('createdBy.id') throws, so the portable Criteria cannot express such a filter for any backend.

The way round it is to flatten what you filter on — map a dedicated created_by_id field on the document and filter on that instead of reaching into the nested object.

Negation by De Morgan pushdown

Loupe's filter grammar accepts NOT only immediately before IN and BETWEEN — NOT (year > 2000) is a syntax error, there is no way to negate a group. So instead of wrapping a compiled group in NOT, negation is pushed down to the leaves:

• not(A AND B) → not(A) OR not(B); not(A OR B) → not(A) AND not(B)
• not(not(A)) → A
• Comparisons flip to their opposite operator: =↔!=, >↔<=, >=↔<, IN↔NOT IN, IS NULL↔IS NOT NULL, IS EMPTY↔IS NOT EMPTY, BETWEEN↔NOT BETWEEN.

This keeps the core's negative shorthands (notIn(), notBetween(), isNotEmpty(), notStartsWith(), …) working, since they are all not(...) wrappers underneath.

Documents holding no value are kept. Loupe compiles >, >=, < and <= to attribute <op> value AND attribute IS NOT NULL, so they drop documents where the field is empty — while its native !=, NOT IN and NOT BETWEEN keep them. Left alone, that would make the result depend on which compilation path a range happened to take: not(between(1970, 1980)) would return valueless documents through the native NOT BETWEEN, but not(between(1970, 1980, includeLeft: false)) would not, so flipping a bound's inclusivity would silently change the result set. Negated ordering comparisons restore those documents explicitly, which is also what the core specifies — notBetween() is documented as matching "values outside the given interval, including fields holding no value at all".

Browse versus search

Criteria is compiled to one of two Loupe query objects, chosen by what it asks for:

BrowseParameters has no withSort() at all, so any criteria carrying an orderBy() has to go through search(). Conversely, search() results are capped by Configuration::maxTotalHits (1000 by default), while browse() is explicitly designed to walk an entire collection without that ceiling. Browsing is therefore preferred whenever it can do the job — it's both unbounded and the cheaper of the two endpoints.

Escape hatch: native Loupe queries

Facets, highlighting, cropping, distinct and ranking scores are not modelled in the ODM's Criteria — extending it would be a separate, cross-implementation piece of work. They stay one call away by passing a native Loupe query straight to the repository:

ObjectRepositoryInterface::findBy() / findOneBy() accept Criteria, a plain array of equality filters, a native SearchParameters / BrowseParameters, or this package's own LoupeCriteria wrapper (which additionally carries the pagination batch size, see LoupeCriteria::setDefaultBatchSize()).

Schema management

SchemaUpdater walks every registered collection, instantiating each index — which creates its data directory and database on first use — and reports whether the stored index still matches its configuration:

dropSchema() deletes every collection's data directory (or discards the in-memory instance):

Data Transformers

Transform data between PHP objects and Loupe documents:

Built-in transformers

• DateTimeImmutableTransformer: Convert DateTimeImmutable objects to/from strings
• BackedEnumTransformer: Convert backed enums to/from their scalar value
• StringableTransformer: Convert Stringable objects to/from strings
• RelationTransformer: Handle ManyToOne-like relations ⚠️
• RelationsTransformer: Handle OneToMany-like relations ⚠️

⚠️ Since Loupe is not a relational database, it has no foreign key constraints: use this at your own risk!

Custom transformers

Advanced Usage

Custom repository

ObjectRepository (the default repository) is final — compose ObjectRepositoryTrait into your own class instead for domain-specific methods:

Register the repository with the Object Manager as early as possible in your application:

Events

Bring your own (PSR-14 compliant) event dispatcher, and hook your logic to lifecycle events:

Using Loupe for tests without touching your production models

#[AsAttribute] and #[AsIndex] live in this package, so putting them on your entities makes them a production dependency — reading platform metadata instantiates the attribute class, which is a fatal error if the package is only in require-dev.

To keep Loupe strictly a test-time backend, skip the attributes and hand ObjectManagerFactory::create() a $configurator closure instead. It receives the configuration derived from the class metadata plus that class's metadata, and returns the configuration to use:

Your entities keep only the core's #[AsDocument] / #[AsField], and nothing in production depends on this package.

Between tests, IndexRegistry::drop() forgets an in-memory index and deletes an on-disk one, so each test starts from an empty collection:

Differences from honey-odm/meilisearch

Loupe is Meilisearch-shaped, but it isn't Meilisearch, and a few structural differences leak through the adapter:

• One SQLite database per collection, not one server holding every index. There is no way to share a connection between collections, so each mapped class gets its own Loupe instance and its own data directory.
• Configuration is frozen at construction. There is no "push settings to a running index" call like Meilisearch's — needsReindex() reports drift, but reacting to it (re-indexing) is the caller's decision, not this library's.
• No CONTAINS / STARTS_WITH / ENDS_WITH / EXISTS. Loupe has no substring matching, and its index-wide schema makes EXISTS meaningless.
• No group negation, handled transparently by the De Morgan pushdown described above — Loupe's grammar only allows NOT immediately before IN and BETWEEN.
• BETWEEN is numeric-only natively; string ranges fall back to AND-combined comparisons.
• Geo filters take the attribute name — _geoRadius(attribute, …) — rather than a reserved _geo field.
• No asynchronous flush options. SQLite writes are synchronous, so Meilisearch's wait, flushTimeoutMs and flushCheckIntervalMs have no counterpart; the only flush option is flushBatchSize (defaulting to a single batch).

Testing

This package includes comprehensive test coverage using Pest PHP. Unlike the Meilisearch adapter, no external server is required, so the whole suite runs offline:

Code Quality

This project maintains high code quality standards:

• 100% test coverage requirement
• PHPStan level 9 static analysis
• PSR-12 code style, enforced by phpcs
• Pest PHP for testing

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• Honey ODM Core - The core ODM framework
• honey-odm/meilisearch - The sibling Meilisearch adapter
• Loupe - The Loupe search engine