Capsule Laravel Package

Product Decisions This Supports

• Feature delivery in non-Laravel codebases. Lets teams add relational persistence — Eloquent models, the query builder, and migrations — to legacy monoliths, CLI tools, cron workers, WordPress plugins, or small internal services without committing to a full framework migration.
• Build vs. buy vs. borrow. This is a borrow decision, not a build decision. The package is a thin wrapper over illuminate/database, which already ships Illuminate\Database\Capsule\Manager natively. The real product decision to evaluate is “do we standardize on Eloquent outside Laravel?” — this package is only the packaging around that answer.
• Incremental migration strategy. A useful stepping stone: teams write Eloquent models and migrations today in a legacy app and carry that code forward if the service later moves onto Laravel. Lowers the cost of a future framework consolidation and de-risks a bigger rewrite.
• Scope control / avoid bespoke abstraction. Prevents engineering from hand-rolling a data layer. Standardizing on a widely known API (Eloquent) shrinks design and code-review surface area and reduces the number of ways things can be done.
• Team leverage and hiring. Eloquent/query-builder familiarity is abundant in the PHP market, so choosing it for a non-Laravel service reduces onboarding time versus a custom DAL.
• Prototyping and internal tooling. Appropriate for throwaway CRUD admin panels, one-off data migrations, and scripts where durability requirements are low and speed of delivery dominates.

When to Consider This Package

Adopt only if all of the following hold:

• You have a non-Laravel PHP application on Composer and you specifically want Eloquent models or Laravel migrations.
• Your team already knows Laravel/Eloquent — the productivity gain is the entire value proposition.
• The blast radius is small and reversible: internal tooling, scripts, a bounded service, or a time-boxed prototype.
• You are prepared to pin an exact version and, ideally, vendor or fork it, because you are effectively taking ownership of the code.
• You have verified provenance — the package name (dhorrigan/capsule) and linked repository (philsturgeon/capsule) do not match. That mismatch is a supply-chain due-diligence item to resolve before any adoption.

Look elsewhere if any of the following hold:

• You can just use illuminate/database directly. It ships Illuminate\Database\Capsule\Manager, the maintained, first-party version of exactly this. A wrapper around a wrapper adds a dependency without adding capability. This is the default recommendation.
• Maintenance signals matter. Zero stars and zero dependents means no community, no CVE response path, no compatibility guarantees for future PHP/Laravel versions. Treat it as unmaintained software.
• You need a long-term supported data layer. Consider Doctrine DBAL/ORM, Cycle ORM, or committing to a framework.
• You need capabilities Eloquent’s Capsule does not provide: connection pooling at scale, advanced read/write splitting, async/non-blocking drivers, or first-class multi-tenancy.
• You are on PHP or database driver versions outside the supported matrix of the pinned upstream version — Composer resolution against a modern PHP 8.x runtime is the first thing likely to fail.

How to Pitch It (Stakeholders)

One-liner: A tiny adapter that brings Laravel’s database layer to non-Laravel PHP code — cheap to try, but effectively unmaintained, so it should be a tactical spike, not a platform standard.

For executives: The license cost is zero and the integration cost is near zero, but the ownership cost is not. With zero stars and zero dependents, there is no community backing, no security-response process, and no guarantee of future compatibility. The recommendation is not to adopt this package as a standard. Instead, approve a short, time-boxed engineering spike; if Eloquent outside Laravel proves valuable, depend on illuminate/database directly with a pinned version. Budget assumption: we own the code either way, so we should own the smallest possible surface.

For engineering: The API is Capsule\Manager — familiar to anyone who has used Laravel, and the wrapper’s surface area is minimal, so an exit is cheap. Put it behind an internal repository/gateway interface (e.g. a DatabaseBootstrapper) so the ORM can be swapped without touching domain code. Swap the implementation to native Illuminate\Database\Capsule\Manager, remove the wrapper, pin the Illuminate version deliberately, and add a smoke test that asserts connection plus model hydration on every CI run. Instrument for the likely failure modes: Composer resolution conflicts blocking unrelated upgrades, dual-global-capsule class collisions routing queries to the wrong connection, hard failures on PHP minor upgrades, and connection leaks in CLI loops or long-lived workers (Swoole, RoadRunner, queue daemons).

The ask: A time-boxed evaluation (1–2 days), not a roadmap commitment. Success criteria: Eloquent models and migrations working against our target database in a non-Laravel context, with a documented exit path and a pinned dependency. If the spike succeeds, the deliverable is the internal abstraction plus the native Illuminate dependency — not this package.