Luigis Box Bundle Laravel Package

Product Decisions This Supports

• Search-and-discovery vendor selection. This bundle is the cheapest possible way to run a Luigi's Box proof-of-concept in a Symfony codebase: index a catalog, hit search, read facets, and get recommendations without writing an HTTP client. That makes a real bake-off against Algolia/Typesense/Elasticsearch a 1–2 sprint experiment instead of a 1–2 month integration project, which is the decision that actually matters.
• Build vs. buy on the integration layer. The package answers "do we write our own Luigi's Box client?" It ships typed value objects (ContentUpdate, PartialContentUpdate, ContentRemoval, ContentAvailability), a fluent SearchUrlBuilder (filters, preferences, sort, dynamic facets), a recommendations request, and update-by-query jobs with status polling. Buying (free, MIT) here is defensible for a Symfony shop; the build cost you avoid is mostly DTO/exception plumbing, not business logic.
• Indexing and catalog-freshness requirements. Full vs. partial updates vs. removal vs. availability toggles map directly to product states (new SKU, price/stock change, delisting, out-of-stock). Availability-only updates are the cheap path for stock churn — a meaningful lever on API quota and index lag, and worth specifying as an SLO ("out-of-stock reflected in search within N minutes").
• Merchandising operations. Update-by-query with job tracking enables bulk rules ("all green tops get color olive/emerald") without a full reindex. This is the feature that turns search from an engineering artifact into a merchandising tool, so it drives roadmap sequencing and whether you need a merchandiser-facing admin surface (you will — the bundle gives you a job ID, not a UI).
• Multi-brand / multi-locale architecture. ConfigProvider supports named configs, runtime addConfig(), per-config timeouts, and custom headers. That's a decision input for whether one deployment serves multiple storefronts or you spin up per-brand instances.
• Reliability and rate-limit budgeting. The exception taxonomy is unusually decision-friendly: TooManyRequestsException exposes retryAfterSeconds, TooManyItemsException exposes the batch limit, and ApiResponse reports per-document $okCount/$errors with url/type/reason. That directly informs your retry policy, batch sizes, dead-letter handling, and the "partial success" UX question — note $success is false if any document fails, so a naive boolean check will mislead you.
• Performance/latency trade-offs. Separate search vs. content vs. connection timeouts, plus an opt-in search cache capped at 300s by Luigi's Box itself. That 300s ceiling is a product constraint: it bounds how fresh cached search results can be, which interacts with flash-sale and "new arrivals" experiences.

When to Consider This Package

Consider it when:

• You are on Symfony 6+/PHP 8.2+ (v4.x) or Symfony 7+/PHP 8.4+ (v5.x) and already hosting Luigi's Box or actively trialing it.
• Your team is small and you want typed request/response objects and pre-mapped HTTP error semantics rather than hand-rolling them.
• You need multi-config (multi-brand, multi-locale, staging vs. prod keys) and per-request header injection without forking a client.
• You want merchandising bulk updates and can tolerate polling a job status endpoint rather than receiving webhooks.
• You value MIT licensing and zero procurement friction for a PoC.

Look elsewhere, or budget adapter work, when:

• You are on Laravel. This is a Symfony bundle — no service provider, no Laravel config publishing, no facade. It is a reference implementation, not a dependency. Realistically you'd port the DTOs/exception mapping (~a few days) or call the API directly. Do not put "install this package" on a Laravel roadmap.
• You are pre-Symfony 6 / pre-PHP 8.2 (v4 dropped both) or on a legacy monolith with no upgrade appetite.
• You need an official, vendor-supported SDK or a support contract/SLA. Luigi's Box does not publish this; a retailer's internal bundle (Answear) is not vendor-endorsed.
• Due diligence signals matter to your org: 7 stars, 0 dependents, no downstream validation, README-and-releases-only documentation, no stated deprecation/branching policy. Majors have already carried BC breaks (Symfony <5.4, then <6 + PHP <8.2), so each upgrade is real work.
• You need async/queued indexing, batching orchestration, backoff, or observability beyond what a synchronous HTTP wrapper gives you. All of that is yours to build on top.
• Your only requirement is "search box on a small catalog." A few hundred lines against the REST API may be cheaper to own than a low-traffic third-party bundle.

How to Pitch It (Stakeholders)

To executives: Luigi's Box is a buy-decision we can de-risk in weeks, not quarters. This package — MIT, actively released (up through Symfony 7 / PHP 8.4, with recommendations and dynamic facets added in recent versions) — removes the integration engineering from the equation, so the real conversation becomes commercial: license cost, relevance quality, and merchandising control. It lets us run a credible bake-off and get a search experience in front of customers fast. Two caveats to state plainly: it is an open-source bundle maintained by one retailer, not an official Luigi's Box SDK, and it is Symfony-only — if we standardize on Laravel, we own a small adapter ourselves.

To engineering: This is a thin, typed Symfony integration, not a framework. What you get for free: config-driven multi-tenant credentials with dynamic override, split timeouts (connection/request/search) and a search cache TTL you control up to Luigi's Box's 300s hard limit, DTOs for full/partial/removal/availability content updates, a fluent search URL builder with filters/prefer/sort/facets, recommendations, and update-by-query with job polling. Error handling is the strongest part: distinct exceptions with actionable payloads (retryAfterSeconds, batch limit, raw response), and per-document errors with URL/reason so partial failures are diagnosable.

What we still own, and should plan for: queueing/retry orchestration around those exceptions (the bundle is synchronous HTTP), treating $success === false as "inspect $errors" rather than "retry everything," an idempotent full-resync job as a safety net, and metrics on index lag and error rate. Mitigations for the maturity risk: pin an exact version, wrap the bundle behind our own SearchGateway/IndexGateway interfaces so swapping to a direct client or another vendor is a one-file change, and keep the integration confined to one module. Do not let its DTOs leak into controllers or domain models.