Download the PHP package pollora/meilifacets without Composer

MeiliFacets is a Pollora module that adds faceted product listings and a site-wide search panel, served by Meilisearch straight from the visitor's browser. It is for WooCommerce and content sites built on Pollora: the first page is rendered by PHP with the URL's filters applied, and every later click is one request to the engine, with no WordPress page load in the loop.

You want to…

• install it;
• see what a page needs;
• know what the module does;
• understand how a page is served;
• know what you get without writing PHP;
• know the rules the module is built on;
• find the right page;
• work on the module itself.

Installation

MeiliScout 2.5.1 or later comes with the module. The project's composer.json needs an installer-paths rule and merge-dev: false first, and the module is then enabled in modules_statuses.json: the whole sequence is in Installation.

Requirements

Quick start

A product listing, composed from the module's Blade components:

A search panel in the header:

What it is

Two features, both served by Meilisearch:

• Listing filters. Facets by taxonomy or product attribute, a price range, sorting, pagination, active filters, a search field that narrows the list, and a mobile drawer.
• Site search. A magnifier in the header opens a panel with one section per content type: products, posts, pages and any indexed custom post type, with a result count and a link to the full results.

What it does not do: it does not index anything itself, and it does not replace WordPress's routing or templates. MeiliScout, a WordPress plugin, builds and pushes the documents.

How it works

• The server renders the first page with the filters of the URL already applied. The page is complete without JavaScript, and search engines see real content.
• After that, every check, sort, page or search term is a single request from the browser to Meilisearch. The client rewrites the address bar, so a filtered view can be bookmarked and shared.
• The engine computes the results and the facet counts in a few milliseconds. A full WordPress page load is avoided on every click, while WordPress keeps the URLs, the routing and the SEO.
• MeiliScout indexes, MeiliFacets queries. The module adds its own fields (facets, card, price…) to the documents MeiliScout builds, and declares the index settings it needs.

What you get without writing PHP

On a WooCommerce project, with MeiliScout indexing products:

• a product listing named products, filtered by category and brand;
• sorting by relevance, price low to high, price high to low and newest; « On sale » is added when you declare a price filter;
• cards with the image, title, link and the price as the shop displays it, taxes included or not;
• a site search over every public post type MeiliScout indexes, products first.

Everything else (other facets, the price filter, your own card, other sorts) is a configuration key, a view override or a container binding. See Quick start.

Design principles

• The URL is the state. WordPress's own paths are kept, filters travel as query parameters, and the server applies them on first render.
• Behaviour in the module, appearance in the theme. Every view can be overridden from the theme. The stylesheets are neutral and tuned with CSS custom properties.
• Hooks, not classes. The browser client binds to data-meili attributes, never to a class name. A theme changes tags and classes freely as long as it keeps the hooks.
• Every shop-specific choice is a contract with a default. Facets, sorts, the card, the searched fields and the searched types each sit behind a PHP interface. A project with nothing to declare gets a working listing; a project that binds its own implementation wins.
• The browser key is public, so the index exposes little. The search key travels to every visitor. The index only lets it read ID, card and parent_id, and it must only hold published content. See Going to production.

Documentation

Installing a module with Composer, and the installer-paths rule it needs, is covered on pollora.dev/advanced/modules. The module's own guide lives in docs/:

Reading this documentation

• Commands are written without a container runner: php artisan …, wp meiliscout index, composer …. Prefix them with yours when PHP runs in a container (ddev exec php artisan …, ddev wp …, docker compose exec …).
• <theme> stands for the active theme's folder. A view override lives under <theme>/resources/views/modules/meilifacets/….
• Component tags are written with their full prefix: <x-meilifacets::listing.facet>.

Map

The maintainers' design notes, in French, are in docs/internal/: decisions, measurements and known traps gathered while building the module. They are not needed to use it.

Development

Run these from a clone of the module's repository, not from a copy installed in a project. The repository keeps its own node_modules, which only serves the system that installed it. Node 24.12 or later is required.

The Feature tests render Blade views and need a host application. Run them from a Pollora project where the module is installed, with a PHPUnit suite that includes Modules/MeiliFacets/tests/Feature.

Commits follow Conventional Commits. Before opening a pull request, composer check and the Feature tests should both pass. The current release is 0.3.0, a beta: see the changelog.

Contributing

Contributions are welcome: see the contributing guide. Report security issues privately, as described in the security policy.

License

MeiliFacets is open-source software licensed under the RuBee group