Laravel Cycle Orm Adapter Laravel Package

Product Decisions This Supports

• Build vs. buy on the persistence layer. The decision isn't "Eloquent or Cycle" — it's "do we invest engineering weeks building our own Data Mapper bridge, or adopt a maintained MIT adapter?" This package converts an unbounded internal R&D project into a bounded integration cost, which is the cleanest framing for a buy decision.
• Architecture posture: DDD vs. CRUD. If the roadmap includes rich domain models, aggregates, invariants, and a persistence-ignorant core (e.g., a billing, pricing, or compliance domain), this is the enabling dependency. If the roadmap is feature-velocity CRUD, it actively works against you.
• Framework upgrade planning. The compatibility matrix is unusually legible — Laravel 10.28/11/12/13 mapped to adapter versions and PHP 8.2→8.3 floors. That's a real input to your annual upgrade budget: adopting this pins you to the maintainer's release cadence for Laravel 13+, and the 6.0.0 release shows a breaking PHP floor bump (8.3) bundled with framework support. Plan for coordinated upgrade windows, not drop-in upgrades.
• Persistence-layer optionality as a hedge. A DataMapper boundary means the domain model isn't welded to Eloquent. That has product value beyond elegance: it de-risks a future move to Doctrine, raw SQL, or a different framework, and it makes a services-extraction or modular-monolith split materially cheaper.
• Testing strategy and CI cost reduction. DataMapper + unit-of-work lets domain logic be tested without a database, shrinking integration-test surface and CI wall-clock time. That's a measurable line item, not a vibe.
• Roadmap scoping for "coexistence." Because Cycle and Eloquent can run side by side, this supports a phased, strangler-style adoption of one bounded context at a time rather than a big-bang rewrite. That sequencing is a PM decision, and it's the most defensible way to spend the risk.

When to Consider This Package

Adopt when:

• You have (or are committing to) a genuinely domain-heavy bounded context where Eloquent's Active Record coupling is already causing pain — fat models, observers/events doing business logic, tests that need a database to assert a rule.
• You need DataMapper semantics specifically: identity map, unit of work, lazy loading, embeddables, explicit mapping — not just "a different query builder."
• You already run Cycle ORM elsewhere (e.g., a Spiral service) and want consistency across services rather than two ORMs.
• You want persistence ignorance as a stated architectural principle, and you have at least one engineer who has shipped a DataMapper ORM before.
• You're on Laravel 11–13 / PHP 8.3+ and can track the adapter's major releases.

Look elsewhere when:

• The app is CRUD-shaped or the domain is thin. Eloquent is faster to build, better documented, and every Laravel developer already knows it. This package would be a tax with no return.
• You depend heavily on Eloquent-assuming ecosystem packages — Nova, Scout, some auth/permission and audit packages, Model:: factories, observers, policies. The adapter does not make those work; you will rebuild or abandon them.
• Adoption signal matters to you. 34 stars and zero dependents is a thin evidence base. There is no enterprise support contract, no visible production case-study list, and the release cadence is driven by a single small organization. Treat this as a bet on one maintainer's continued attention, and price that risk explicitly.
• You need guaranteed LTS or a vendor SLA. MIT + small org means your mitigation is a fork-and-maintain contingency, which must be staffed and budgeted before adoption, not after.
• You can't absorb a second ORM's mental model. Two persistence paradigms in one codebase is a permanent onboarding cost and a recurring source of "which ORM owns this table?" confusion. If the team is junior or the codebase is already inconsistent, don't add this.
• Alternatives fit better: wakebit/laravel-cycle (same problem, different implementation — worth a bake-off) or staying on Eloquent with a repository abstraction, which delivers 60–70% of the decoupling benefit at 10% of the cost.

How to Pitch It (Stakeholders)

For executives — one paragraph: "We're evaluating a small open-source adapter that lets our Laravel application use a more rigorous ORM underneath our most complex business domain, without leaving Laravel. It's MIT-licensed and free, and it's the difference between our pricing/billing rules living in code we can test in isolation versus being tangled into database models. The trade-off is honest: it's a niche package (34 GitHub stars, no downstream dependents) maintained by a small team, so adopting it means we own a contingency plan and an engineer who understands it. My recommendation is a scoped spike in one bounded context — not a company-wide standard — so we can measure the testing and coupling benefit against a real cost before committing."

For engineering — the substance:

• What it is: a Laravel service-provider bridge for Cycle ORM 2.x — wiring, config, container bindings, testing helpers. The ORM itself is mature and independently maintained; the adapter is the thin, replaceable part. That distinction matters for the risk story: the adapter is ~a few hundred lines of glue, so forking is genuinely feasible.
• What you get: DataMapper separation, unit of work, identity map, explicit schema mapping, domain objects with no framework base class, DB-free unit tests.
• What you give up: Eloquent's ergonomics and ecosystem, artisan generator conventions, Eloquent-based package compatibility, and the ability to hire "just a Laravel dev."
• What we must build: mapping definitions for adopted entities, migration/seed tooling alignment, an integration-test harness, and a documented pattern for Eloquent↔Cycle coexistence so the boundary is enforceable in review.
• Quality signals in its favor: conventional commits, changelog automation, Codecov and Stryker mutation testing, PHPStan level 5, explicit compatibility matrix, and prompt Laravel 12/13 support. For a package this small, the engineering hygiene is above the median — this is the strongest argument in the deck.
• Ask: two engineer-weeks for a spike in one bounded context with a written go/no-go against measured criteria (test-suite runtime, coupling metrics, LOC removed from models). Contingency owner named up front.