Meilifacets Laravel Package

Technical Evaluation

Architecture fit. MeiliFacets sits at the seam between three systems: WooCommerce as the source of truth for catalog and merchandising settings, Meilisearch (via the sibling MeiliScout package) as the query/index layer, and a Blade/Acorn-style theme for rendering. Its core architectural premise is dual rendering — the same listing is produced on the server and rehydrated by a browser script that clones templates and reads data-meili attributes — so feature value depends on parity between those two paths. 0.2.3 meaningfully improves the extension story: Contracts\DefaultSortedListing and Contracts\CardComponentListing are explicit, publishable seams that let a project declare its own default order and render results with its own Blade card without forking the package. That is the right shape for a themeable WordPress product, and it moves the integration cost from "patch the vendor views" to "implement a contract."

Integration feasibility. Feasible for a team already on Pollora/Acorn with Blade, Meilisearch, and MeiliScout provisioned. The upgrade is mechanically short (composer update, wp meiliscout index, php artisan module:publish MeiliFacets, cache purge) but not self-executing: the published view copies, one config key, one component prop, and one CSS selector contract all changed. It is a developer-assisted upgrade, not a plugin auto-update.

Technical risk. Elevated for a beta, and the risk is concentrated in silent breakage rather than hard failures. The meilifacets.drawer.row_limit → meilifacets.drawer.row.limit rename is not read from the old key, so a missed config change degrades quietly to the default limit. Published views drift on every copy-affecting release (results, drawer, facets again in this version), and listing.card-template is removed outright. The :card → :binding="CardBinding::of($card)" signature change and the [data-apply] selector moving to the listing root will break theme CSS without an error. The package also explicitly warns its PHP classes/interfaces and data-meili attributes may change before 1.0. Separately, the most operationally serious known issue — one reindex per WooCommerce meta write, each resending index settings, able to outrun the engine's queue during bulk edits or imports — is a MeiliScout defect, so mitigation depends on a team outside this package's release cadence.

Key questions. Is MeiliScout a hard dependency, and which version pairing is supported? Does the browser script ship prebuilt or require a theme build step? How should a project track which vendor views it has copied so upgrades can be diffed? What is the support policy for 0.2.x — patch-only, or will minor releases keep breaking the theme surface? Is there a rendering/performance envelope for the card-component path on large catalogs, and does it hold under full-page caching? Who owns Meilisearch queue health and reindex scheduling?

Integration Approach

Stack fit. Best fit is a Pollora/Acorn or Sage-style theme on WordPress + WooCommerce with Meilisearch via MeiliScout, where Blade components and a module publish workflow are already normal. Classic PHP themes without a Blade/Acorn layer are a poor fit — the card-component model and the published-view override pattern both assume it.

Migration path. Treat 0.2.3 as a small breaking release. On a staging clone of the catalog: pin the exact version in composer.json, run the three upgrade commands, rename the config key before deploying so the new key is authoritative, republish the three view copies and re-apply any intentional theme customizations, update <x-meilifacets::listing.card> call sites to :binding="CardBinding::of($card)", remove references to listing.card-template, move .meilifacetsFacets[data-apply] rules onto the listing root, and only then clear the page cache. Optionally adopt CardBinding::standalone() for carousels rendered outside a listing, which also clears the "misplaced card" console noise.

Compatibility. Pre-1.0, so assume minor versions can break the public surface; use an exact pin plus lockfile and read docs/upgrading.md on every bump. Verify the supported PHP/Laravel/WooCommerce/MeiliScout matrix rather than inferring it, and confirm the index schema and data-meili attribute names still match after the reindex.

Sequencing. Config rename and view republish first (cheap, reversible), then asset republish and theme rebuild, then reindex, then cache purge — reindexing before the theme is ready leaves the browser script reading attributes the templates no longer emit. Validate in this order: default product sorting under both no-filter and variation-filter states, row-overflow="show-more" with the drawer parity, a card-component listing on server and client, no-JavaScript fallback past the row limit, then a bulk product save to observe index-queue behaviour. Promote to production outside an import window.

Operational Impact

Maintenance. The published-view pattern is a standing fork point: every release that touches results, drawer, or facets turns into manual diff-and-reapply work for the theme team. Minimize copies, keep overrides in a version-controlled directory with a note of the upstream version they were taken from, and add an upgrade checklist to the runbook. Budget for one or two more upgrade passes before 1.0 given the explicit beta warning.

Support. Merchandisers gain real levers — WooCommerce default sorting is now respected server- and client-side, and the row limit can surface the first filters inline with the rest behind "Show more." That shifts support tickets from "the listing is broken" to "the order is wrong" (WooCommerce catalog settings; note that Popularity and Average rating still cannot be the default order) and "the filters button does nothing" (the side sheet past the row limit requires the browser client to start). Document both for content editors.

Scaling. The dominant scaling risk is write-side, not read-side: reindexing once per product meta write, with index settings resent each pass, can let a bulk edit or import outrun the Meilisearch queue and leave results stale — and the fix is upstream in MeiliScout. Plan for throttled imports or a maintenance window, and monitor queue depth as a first-class signal. On the read side, per-listing Blade card components add render work, but cached pages plus client-side rehydration keep the steady-state cost modest; freshness of the index is what users actually perceive.

Failure modes. Silent config fallback after the key rename; stale copied views producing broken markup post-upgrade; inert filters, sort, or "Show more" when the browser client fails to boot, compounded by the known issue that a failed browser search shows no message and leaves the unapplied filter in the URL — which makes for confusing, shareable broken links; single-selection facets hiding their other values after a pick, blocking users from switching options; variant-per-term double counting inflating facet counts; attribute archives showing the wrong variant; and queue backlog producing stale catalog results. Most are degraded-but-visible rather than outage-class, except the queue issue during bulk operations.

Ramp-up. One developer familiar with WooCommerce and Meilisearch should complete staging upgrade plus theme changes in a few days, with merchandiser enablement measured in hours. The genuinely scarce skill is Meilisearch index operations, and the critical cross-team dependency is whoever owns MeiliScout and the indexing queue — bring them in before scheduling the rollout, not after the first bulk import.