Candy Api Laravel Package

Technical Evaluation

Architecture fit. getcandy/candy-api is a Laravel package that embeds a full commerce domain — catalog, variants/pricing, taxonomies, carts, checkout, orders, customers, payments, shipping, discounts — directly into the host application's process and database. It is an API-first monolith rather than a service: routes are registered by the package's service provider, controllers return resource-transformed JSON, and all state lives in candy_* tables inside your own MySQL instance. This is the right shape if the organization is already a Laravel shop and wants to own the commerce core (no per-order SaaS fees, no external data residency, direct Eloquent access for custom logic) instead of renting Shopify/Commercetools. It is the wrong shape for a polyglot microservices estate or a non-PHP backend, where every integration becomes an HTTP hop against a framework you don't otherwise operate.

Integration feasibility. Mechanically cheap: composer require, run migrations, publish config, seed, issue Sanctum tokens, consume /api/v1/* from a Nuxt/Next storefront. The expensive part is not installation but the convention surface — config-driven class overrides, model resolution through the container, observer-driven side effects, and a search/cart/pricing layer that assumes you'll extend rather than replace. Confirm early: the exact supported PHP/Laravel matrix, which search drivers are wired (database vs. external engine), and whether the payment/shipping integrations you need exist natively or must be written against the package's contracts.

Technical risk. This is the dominant finding. Last release was 2021-09-22; the project was superseded by Lunar (a rewrite with a different data model and lunar_* tables), and the upstream community, issues, and documentation have moved with it. That means: no security patches, no compatibility with Laravel 9+, transitive dependency rot across Sanctum/Spatie/media packages, and a stack whose security-support window has already closed. Mitigations are real but costly — fork, vendor privately, pin the lockfile, and treat the package as first-party source you now maintain. A 437-star count tells you the ecosystem is thin: few third-party extensions and few engineers who have debugging experience with it.

Key questions. (1) Are we willing to own a hard fork and carry Laravel-version risk indefinitely, or is this a 12-month bridge to Lunar? (2) Which commerce capabilities are genuinely differentiated for us versus commodity — i.e., what do we gain by owning this code? (3) Do our payment, tax, and fulfilment providers still support the SDK/API versions the package targets? (4) What is the data-migration cost from candy_* to lunar_* if we later upgrade, and does that change the build-vs-buy math today? (5) What is our exposure if a CVE lands in Laravel 8 or a pinned dependency and we must patch upstream ourselves?

Integration Approach

Stack fit. Target PHP 8.0/8.1, Laravel 8, MySQL 8 (verify Postgres support before committing), Redis for cache and queues, S3-compatible object storage for media, and a Sanctum-token-authenticated SPA/SSR storefront. Admin surface is either the companion Hub/Nova package or custom — budget for it, it is not free. Anything requiring Laravel 9/10 features or PHP 8.2+ is out of scope without a fork.

Migration path. Greenfield is the favorable case: scaffold Laravel 8, install, seed, and go. Brownfield is where the cost hides — there is no supported importer, so products, variants, price tiers, customers, and historical orders must be ETL'd into the candy_* schema by hand, and order history is the usual trap because line-item and address shapes rarely map one-to-one. Plan the schema mapping as a deliverable, not a task.

Compatibility. Treat the dependency graph as frozen. Mirror the package into a private VCS, add it as a path/VCS repository, commit the lockfile, and forbid composer update outside a controlled branch. Document the patch set so a future maintainer can see what diverged from upstream.

Sequencing.

1. Two-week spike: scratch Laravel 8 app, seed catalog, drive a cart through checkout end-to-end against a sandbox payment gateway.
2. Risk-first proofs: payment webhooks (idempotency, retries), tax calculation for our jurisdictions, stock/oversell behavior at checkout, and search quality at realistic catalog size.
3. Fork-and-own decision gate — if the spike passes, formalize the fork and a patch cadence before writing storefront code.
4. Build the storefront strictly against the HTTP contract so the API can later be swapped for Lunar with a client-side adapter layer.
5. Set an explicit Lunar migration review at month 9–12 rather than letting the decision drift.

Operational Impact

Maintenance. This is the largest ongoing cost and it must be staffed, not assumed. Allocate roughly 15–25% of one senior Laravel engineer for dependency patching, CVE triage, and upstream divergence management — plus a standing obligation to evaluate an exit. The absence of upstream releases means every future Laravel or PHP upgrade is a fork-maintenance project, not a version bump.

Support. No vendor, no SLA, no active maintainers on this line. The practical support model is internal ownership, optionally supplemented by a consultancy familiar with the Lunar lineage. GitHub issues and the original docs should be assumed stale; institutional knowledge walks out the door with the engineer who did the fork.

Scaling. The architecture scales the boring way: stateless PHP-FPM behind a load balancer, Redis for sessions/cache/queues, read replicas for catalog reads, external search for query load, media on object storage. Watch the write path — cart and checkout are transactional against a single primary, and the observer-heavy model layer makes it easy to add hidden synchronous work to every order. Keep order confirmation, emails, and webhooks on queues from day one.

Failure modes. The realistic ones: stock oversell from non-idempotent checkout submission; duplicate order or payment capture on webhook redelivery; silent breakage when a payment provider deprecates the API version the package's integration targets; slow drift when someone runs composer update; tax or discount miscalculation surfacing only in production edge cases; and the strategic failure of quietly running an unpatched framework past its support window because nothing has broken yet.

Ramp-up. One to two weeks for a Laravel-fluent engineer to ship against the API; four to six weeks to be genuinely productive inside the domain layer and its override conventions. Non-Laravel engineers should be assumed unproductive on the internals regardless of seniority. Document the fork, the schema map, and the checkout state machine early — those three artifacts are what make this maintainable by someone other than its author.

Bottom line. Viable as a pragmatic, owned-commerce-core bet for a Laravel shop with the appetite to fork and the discipline to migrate — not viable as a low-ownership dependency. The 2021 release date is the deciding fact, and the business case should be written as "build on a known-EOL base with a funded exit," never as "adopt a maintained package."