Commerce Support Laravel Package
aiarmada/commerce-support
Shared foundation for AI Armada's Laravel commerce packages, offering common support utilities, helpers, and base classes that keep storefront, cart, and checkout modules consistent and easy to integrate.
Technical Evaluation
Architecture fit
commerce-support is the shared kernel of the aiarmada/commerce monorepo — the package every other commerce module (including the filament-* adapters) depends on. Based on the repository contract, it owns cross-cutting primitives rather than domain behavior:
- Configurable, prefixable table resolution (
getTable()resolved from package config, with per-instance override support for self-join aliases). - UUID primary/foreign keys as a suite-wide identity convention, with integrity enforced in application code rather than the database.
- A configurable
json_column_typeso JSON columns stay portable across MySQL/Postgres. CommerceNavigation, the engine that lets any Filament resource's navigation group/sort/label be overridden at runtime viacommerce-support.filament.navigation.items.{FQCN}.
That is the correct shape for a commerce suite. Table-prefix remapping, key-type consistency, and a single navigation merge point are exactly the things that rot when each module invents its own. The trade-off is that "support" is not domain-agnostic: it carries a Filament-facing navigation engine, so we pay Filament coupling even for modules with no admin surface.
Integration feasibility
Low technical friction, given the right platform. MIT license, Composer-installable, conventional Laravel package layout with required docs (01-overview, 02-installation, 03-configuration, 04-usage, 99-troubleshooting) and per-package CONTEXT.md routing documents. The blocker is not install mechanics — it is the runtime floor.
Technical risk
| Risk | Severity | Evidence / rationale |
|---|---|---|
| PHP 8.5+ only | High | "Target PHP 8.5+ only." Adopting any package in the suite forces the entire application runtime, CI image, and managed-hosting support onto a bleeding-edge PHP minor. |
| No backward-compatibility guarantee | High | "Breaking changes are allowed when they improve the system. Backward compatibility is not required unless a task explicitly asks for it. Do not add backward-compatibility shims." Composer ^ ranges are not a safety net here. |
| Zero external validation | High | 0 stars, 0 dependents, score 0. No public signal of production use, no third-party bug reports, no ecosystem answers. |
| Database integrity in application code only | Medium-High | "Never add database-level constraints or cascades: no ->constrained(), no cascadeOnDelete(), no FK constraints." Orphan rows and concurrent-delete races become our problem, not the DB's. |
In-place migration edits, no down() |
Medium-High | "Evolve schema by editing the owning migration in place; do not add a new migration file per schema change… No down() method is required." Deployed environments can silently miss schema changes because Laravel tracks migrations by filename. |
| Filament v5 coupling | Medium | Filament v5 is itself new. Two young dependencies in one critical path compounds upgrade risk. |
| Quality-gate ambiguity | Medium | Guidelines mandate per-package Pint/PHPStan/Pest and explicitly discourage repo-wide runs. Coverage and CI matrix must be verified directly — the docs describe intent, not enforcement. |
| Octane/long-lived-worker correctness | Medium | The rules exist because the failure mode is real: static mutable state leaking across requests. The navigation engine is explicitly stateful-ish (config defaults merged with runtime overrides) and needs soak testing. |
Key questions to put to the maintainers before any commitment
- Is
commerce-supportpublished to Packagist, or must we consume it via a VCS/path repository? Is there a versioning policy beyond "breaking changes are allowed"? - What is the CI status and coverage per package? Is Pint/PHPStan/Pest actually gating merges?
- Why PHP 8.5 specifically — language feature, or just the maintainer's local runtime? Is a 8.3/8.4-compatible branch feasible, and would it be maintained?
- Is there a changelog or upgrade guide per release? How are breaking changes communicated?
- Commit cadence and maintainer count over the last six months — is this actively developed or a paused internal project?
- Can the Filament-dependent pieces (
CommerceNavigation) be split from a headless support kernel? If we build API-first, we should not drag in Filament. - Which Laravel version range is supported? The excerpt does not state it, and that is a hard compatibility gate.
- Is
CommerceNavigationload-bearing, or a convenience wrapper over Filament's native navigation that we could bypass?
Integration Approach
Stack fit
The package presupposes a specific application shape: Laravel, PHP 8.5+, Filament v5, Octane/Horizon long-lived workers, Laravel Actions for orchestration, CarbonImmutable for time, UUID keys, and no database-level referential integrity. If that is already our baseline, integration is a Composer line item. If it is not, the real project is a platform upgrade — PHP, CI images, hosting, and every other dependency's compatibility — and commerce-support is merely the trigger.
Migration path — three viable options
| Option | When it applies | Cost |
|---|---|---|
| Greenfield adoption | New application, no legacy schema conventions, Filament admin from day one | Lowest friction; adopt the full convention set from commit one |
| Brownfield, kernel only | Existing Laravel app that wants the shared primitives, not the suite | Must reconcile UUID vs. existing bigint keys and table prefixes; partial adoption risks two conventions coexisting |
| Vendored fork at pinned commit | Any production commitment under the current BC policy | One-time fork, ongoing rebase cost; converts an external risk into a known internal one |
Recommendation: do not adopt transitively. If we take a single vertical module (e.g. cart), commerce-support arrives with it — decide about the kernel before the first module, not after.
Compatibility verification
- Confirm Composer constraints for PHP, Laravel, and Filament in
composer.json— the excerpt states intent, not the actual range. - Exercise
json_column_typeagainst our actual database. If Postgres, verifyjsonbis selectable and that any JSON query paths use GIN indexes. - Verify table prefixing and remapping under a real deployment config, including the self-referencing
getTable()alias path — that is the single subtle bug called out in the model rules. - Confirm Octane safety under load: worker restart, config cache enabled, and navigation overrides applied.
- Verify migration publish/re-run semantics in a database that already has the migrations recorded.
Sequencing
- Due diligence gate — publish channel, versioning policy, CI status, maintainer cadence, Laravel version range.
- Platform upgrade in isolation — move runtime/CI to PHP 8.5 with no new packages. This de-risks the single largest item and is independently valuable.
- Kernel spike — scratch app: install
commerce-supportonly, publish config and migrations, run them, assert UUID keys, table-prefix resolution, and a runtime navigation override taking effect. - One vertical slice — adopt a single commerce module end to end, including a schema change, to learn the in-place-migration workflow before it touches production.
- Convention rollout — publish internal guidance mirroring the
.ai/rules (UUID, no FKs,getNavigationGroup()from config, Actions for orchestration) and enforce in review/PHPStan. - Decide on fork-and-pin before the second module lands.
Operational Impact
Maintenance
The dominant ongoing cost is the no-BC policy. Every release is a potential minor-version breaking change; budget upgrade work as a recurring line item, not a one-off. Pin exactly, read the diff, and stage upgrades. The in-place-migration convention compounds this: "run migrations" is no longer a safe deploy step, because a shipped migration file may have changed content without changing its recorded name. Add a pre-deploy check that diffs vendor migration files against the last deployed commit, and treat unexpected diffs as a release blocker.
Support
Effectively self-support at 0 stars and 0 dependents. The issue workflow (canonical labels: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix) is well-defined, which suggests a disciplined maintainer, but there is no third-party knowledge base, no Stack Overflow corpus, and no vendor SLA. Mitigation: designate an internal owner for the commerce kernel, mirror the package docs into our own knowledge base, and assume escalation means reading source.
Scaling
- UUID keys: good for distributed writes and non-enumerable identifiers; worse than
BIGINTfor InnoDB clustered-index locality. Page splits and secondary-index bloat are real on high-volume cart/order rows. Quantify before volume commitments — if we expect millions of rows, ordered UUIDs or a key-type strategy matters. - Application-level cascades: deleting a parent with many children becomes O(n) application work with partial-failure semantics. It needs to be a queued job with idempotent retry, not a synchronous
delete(). Plan for periodic orphan-detection sweeps as a standing safety net. - JSON columns: configurable type is genuinely good for portability. On Postgres, standardize on
jsonbwith GIN indexes where queried; do not let ad-hocjsoncolumns accumulate.
Failure modes to instrument
- Orphaned child rows after a partially failed application-level cascade (no FK will stop it).
- Concurrent parent-delete and child-create racing the app-level cleanup path.
- Schema drift between environments caused by edited-in-place migrations that never re-ran.
- Navigation overrides silently diverging from config defaults — a resource in the wrong menu is now a config-merge debugging exercise, not a code bug.
- Static state leaking under Octane; the rules exist precisely because it is easy to reintroduce.
- PHP 8.5 floor blocking a security patch or a dependency upgrade we need.
- Filament v6 forcing an upgrade of
filament-*adapters that transitively re-pin the support kernel.
Ramp-up
Roughly one to two days for a senior Laravel engineer to be productive, plus one platform day for the PHP 8.5 move. The onboarding surface is non-trivial: the .ai/ rule set is effectively mandatory reading (UUID keys, no FK constraints, getTable() instead of $table, getNavigationGroup() from config, Actions for multi-step orchestration, CarbonImmutable, per-package tooling). Treat those rules as enforced requirements — verify PHPStan and review actually catch violations, because a convention that is only documented will drift within a quarter.
Gate
No-go until the due-diligence questions are answered and the PHP 8.5 platform move is independently validated. If those clear, proceed with a vendored, pinned fork and a single vertical slice — not as an unpinned Composer dependency, and not across multiple modules at once.
How can I help you explore Laravel packages today?