Luigis Box Bundle Laravel Package

Technical Evaluation

Verdict: A small, purpose-built API client wrapped as a Symfony bundle. The reusable value is the DTO/response mapping layer (ValueObject, Response, Service namespaces) covering Luigi's Box content updates, search, update-by-query, and (since 4.1.0) recommendations. The framework glue is thin and Symfony-specific, so the "Laravel package" framing in our intake is inaccurate — treat this as a Symfony library we would adapt, not adopt.

Architecture fit. The bundle sits at the edge of the domain: it maps our catalog objects to Luigi's Box documents (ContentUpdate, PartialContentUpdate, ContentRemoval, ContentAvailability) and maps search responses back into SearchResponse/Hit/Facet objects. That is a clean seam — an application-layer port. It does not own indexing policy, document schema, or sync orchestration; those remain ours. For a Laravel codebase the DI extension and configuration tree are dead weight, but they are separable: the request/response/value-object classes are framework-agnostic and only need Guzzle plus config values to run.

Integration feasibility. Composer-installable, MIT, PHP 8.2+ and Symfony 6/7 per 4.0/5.0.0. Multi-config support (configs, default_config, ConfigProvider::setConfig) and dynamic config (addConfig with ConfigDTO) are useful for multi-store/multi-locale setups. Transport is Guzzle since 2.4.0, which aligns with our existing HTTP stack. The friction is that a Symfony bundle expects symfony/http-kernel/dependency-injection/config and very likely framework-bundle; Laravel does not load bundles, and pulling Symfony's full framework kernel into a Laravel app to serve one API client is disproportionate.

Technical risk.

• Framework mismatch (medium): highest-likelihood source of wasted effort; verify transitive requirements before committing.
• Vendor sustainability (medium-high): 7 stars, 0 dependents, single-company (Answear) maintenance, no commercial support. Major versions 3.0 → 4.0 → 5.0 each carried BC breaks and PHP/Symfony floor raises — roughly annual churn with no deprecation runway promised.
• API drift (medium): the bundle absorbs Luigi's Box API changes only when maintainers ship; MalformedResponseException is our early-warning signal.
• Correctness semantics (medium): ApiResponse::$success is false if any document fails, while $okCount/$errors describe partial success. Partial-failure reconciliation is application work the bundle does not do for us.
• Data hygiene (low): the recorded last release date (2026-10-09) is in the future relative to normal release cadence; confirm tag provenance before pinning.
• Code risk (low): small surface, explicit exception taxonomy (TooManyItemsException::$limit, TooManyRequestsException::$retryAfterSeconds), MIT allows vendoring if upstream stalls.

Key questions.

1. Does the bundle hard-require symfony/framework-bundle, or only the DI/config components? This determines whether we adapt in place or fork the core.
2. Is there an official Luigi's Box PHP SDK, and does it cover content updates + search + recommendations equivalently? If yes, the bundle's main advantage (typed DTOs) may not justify the wrapper.
3. What backs searchCacheTtl (PSR-6/Symfony cache)? Can we point it at Redis, and is the 300s ceiling acceptable for our freshness expectations?
4. What are Luigi's Box's per-request document limits and rate limits for our contract tier?
5. Do we need recommendations and dynamic facets now, or only search + content sync (which would let us pin an older, simpler major)?
6. Are search queries or document fields subject to PII/data-residency constraints in our region?
7. Who owns this code if upstream goes quiet — do we have a named maintainer and a fork policy?

Integration Approach

Stack fit. Laravel 10–12 on PHP 8.2+ is compatible at the language level and shares Guzzle and Symfony 6/7 components with the bundle. The idiomatic fit is: a Laravel service provider binds a LuigisBoxClient interface; a thin adapter constructs ConfigProvider from config/luigisbox.php (mapping publicKey, privateKey, host, connectionTimeout, requestTimeout, searchTimeout, searchCacheTtl); domain code depends only on our interface, never on Answear\LuigisBoxBundle\*. Index writes go through queued jobs, not request handlers.

Migration path. Assume an incumbent search (SQL LIKE, Laravel Scout, or Elasticsearch). Stand up Luigi's Box in parallel: dual-write index updates via queued jobs, add a feature-flagged search driver behind our existing search abstraction, and compare relevance and latency on real queries before cutover. Keep the incumbent readable for at least one full reindex cycle so rollback is a flag flip, not a data migration.

Compatibility. Pin an exact major (5.x) and treat upgrades as planned work, not patch bumps — every prior major dropped PHP/Symfony floors. Verify Composer resolution against Laravel's pinned symfony/* versions before estimating. If framework-bundle conflicts, fork or vendor the ValueObject/Response/Service namespaces behind our own provider; MIT makes this legitimate and the surface is small. Confirm the release tag's provenance given the anomalous date.

Sequencing.

1. Spike (2–3 days): install under Laravel, construct ConfigProvider manually, execute one real search and one content update against a sandbox index. Gate: does it run without the Symfony kernel?
2. Adapter + config (3–5 days): interface, service provider, config file, exception-to-domain-error mapping, logging.
3. Content sync (1–2 weeks): Eloquent observers/events → queued ContentUpdate/PartialContentUpdate/ContentRemoval batches; per-object-type batching within TooManyItemsException::$limit; availability toggles wired to stock/status.
4. Search (1 week + tuning): endpoint via SearchUrlBuilder, cache layer honoring the ≤300s TTL, fallback driver.
5. Recommendations (optional): wire the 4.1.0+ recommendation requests and their dedicated timeouts.
6. Update-by-query (optional): expose UpdateByQuery + getStatus as an internal admin tool for bulk merchandising fixes.

Operational Impact

Maintenance. Low routine churn, but plan one BC-breaking upgrade per year and budget ~1–3 days each for a Symfony-fluent engineer. If we fork, add upstream release watching and a quarterly diff against the tagged version. No database or infrastructure footprint beyond the app and its cache.

Support. No vendor SLA on the bundle; support comes from Luigi's Box for the API and from a community issue tracker for the code. We must own an internal runbook: key rotation, config validation at boot, index schema changes, and a documented escalation path to Luigi's Box support. One named backend owner is the realistic minimum.

Scaling. All calls are synchronous Guzzle requests — content updates must be queued and rate-shaped, never inline in web requests. Honor TooManyItemsException::$limit by chunking and TooManyRequestsException::$retryAfterSeconds via job backoff; the bundle provides the signals but not the retry policy. Search throughput is bounded by Luigi's Box latency and the ≤300s cache; for hot queries add an application-level cache or edge cache rather than relying on searchCacheTtl. Separate searchTimeout from requestTimeout (2.1.0) so slow indexing does not degrade search.

Failure modes.

• Partial content-update failure: success=false with non-zero okCount means the index is silently partial. Needs a reconciliation job that reads ApiResponse::$errors (url, type, reason, causedBy) and re-queues or dead-letters, plus a dashboard on errorsCount.
• Queue starvation / worker outage: index silently staleness; alarm on sync lag, not just on job failures.
• Search provider outage (ServiceUnavailableException, timeouts): must degrade to the fallback driver; the 300s cache ceiling means the cache absorbs only minutes, not an incident.
• Contract drift: MalformedResponseException spikes indicate the API changed under us — alert on rate, not just occurrence.
• Credential/config errors: BadRequestException exposes request/response; validate keys and host at deploy time rather than at first query.
• No built-in circuit breaker or retry: we implement both in the job middleware and HTTP client layer.

Ramp-up. A Symfony-experienced PHP engineer is productive in 1–2 days from the README alone; a Laravel-only engineer needs ~1 week including the adapter and exception mapping. The real cost is not code — it is index design: object types, URL conventions, field schema, and availability semantics, which is a 1–2 week collaborative effort with merchandising/catalog owners, followed by ongoing relevance tuning. Documentation beyond the README is essentially absent, so budget for writing our own internal integration notes as a deliverable, not an afterthought.