Capsule Laravel Package

Technical Evaluation

Architecture fit. The package addresses a real and recurring need: bringing Eloquent and the query builder into a non-Laravel PHP codebase — legacy monoliths, CLI/cron entrypoints, WordPress plugins, standalone worker services. But the capability is already native to illuminate/database via Illuminate\Database\Capsule\Manager, which has shipped addConnection / setAsGlobal / bootEloquent since Laravel 4.1. This package is a wrapper over that manager, so its architectural contribution is redundant on any modern Illuminate version. The real architectural decision on the table is "do we standardize on Eloquent outside Laravel?" — this package is only packaging around that answer, and a worse form of the packaging than the first-party one.

Integration feasibility. Technically near-zero effort: Composer-installable, tiny public surface, no service provider or container coupling, works with existing PSR-4 autoloading. The blocker is lifecycle, not complexity. With zero stars, zero dependents, and a zero score, this is an unmaintained artifact. It is almost certainly pinned to an end-of-life Illuminate 4.x line, which transitively constrains PHP compatibility and blocks security patching across the stack. Composer resolution against a modern PHP 8.x runtime is the first thing that will fail.

Technical risk.

• Supply-chain provenance (high): the package name (dhorrigan/capsule) and the linked repository (philsturgeon/capsule) do not match. That must be resolved before anything else — it is a due-diligence gate, not a footnote.
• Abandonment (high): no maintainer, no release cadence, no CVE response path, no downstream consumers. The moment we adopt it, it is effectively vendored code we own.
• Version-pin drag (high): a hard constraint on old illuminate/database pins the ORM, which pins PHP, which pins our ability to patch the rest of the stack.
• Namespace/instance collision (medium): the wrapper's Capsule class overlaps conceptually with the native manager; running both in one codebase invites autoload ambiguity and dual-"global" capsule state where queries hit the wrong connection.
• Silent drift (medium): no visible test suite, no consumers, so PHP-version drift surfaces as production incidents rather than CI failures.

Key questions for the team.

1. What Illuminate major does this pin, and what PHP constraint does that imply for our floor?
2. Is there any capability here that standalone illuminate/database does not already provide?
3. Is this already in composer.lock, or is this a greenfield adoption proposal?
4. Who owns the code if upstream disappears — is a vendored fork with a named owner acceptable?
5. Does the target run in long-lived workers (Swoole, RoadRunner, queue daemons) where connection lifecycle matters?

Integration Approach

Stack fit. PHP + Composer only. Appropriate for non-Laravel applications that want Eloquent models and the query builder without the framework. Explicitly inappropriate for anything already on Laravel, where Capsule is bootstrapped for you, and inappropriate as a platform standard anywhere.

Migration path. Treat the package as an adapter, never a foundation. The preferred path is to not take the dependency at all and use the native manager directly:

$capsule = new \Illuminate\Database\Capsule\Manager;
$capsule->addConnection($config);
$capsule->setAsGlobal();
$capsule->bootEloquent();

If the package is already present, the substitution is close to drop-in. The safe sequencing is to put an internal interface (e.g. DatabaseBootstrapper) in front of it first, bind the current wrapper behind that interface, then swap the implementation without touching call sites.

Compatibility. Verify four things in a throwaway branch before any commitment: (a) PHP constraint vs. our runtime floor; (b) illuminate/database constraint vs. everything else in composer.json; (c) PSR-4 mapping and class-name overlap with the native Capsule; (d) PDO driver availability for the target databases. Run composer why-not first — if resolution fails, the evaluation ends there and we have lost an hour, not a sprint.

Sequencing.

1. Dependency spike in an isolated branch: install, boot a connection, run one query builder call and one Eloquent model query, run composer audit.
2. Confirm the upstream version and PHP support matrix; document EOL posture explicitly.
3. Introduce the internal bootstrapper interface; move current call sites behind it.
4. Swap the implementation to illuminate/database + native Capsule\Manager.
5. Remove the package, pin the Illuminate version deliberately, and add a CI smoke test asserting connection + model hydration on every run.

Operational Impact

Maintenance. Assume the full maintenance burden transfers to us on day one. Budget either a vendored fork with a named internal owner and a written patch policy, or a removal ticket with a target date. Do not let it sit as an unowned transitive dependency — that is exactly the failure pattern this package invites.

Support. No community, no downstream consumers, no issue triage, no StackOverflow corpus. All institutional knowledge has to be written down internally. Laravel-fluent engineers will ramp on the code in one to two days because the underlying APIs are familiar; the real cost is organizational — the decision to own dead software, and the review overhead of explaining to future engineers why a wrapper exists over a first-party class that does the same thing.

Scaling. Architecturally neutral: throughput and memory characteristics are entirely Illuminate's. The gaps are operational, not performance. There is no connection pooling, and in long-lived process models the global capsule holds connections open across requests or jobs, so explicit disconnect/reconnect handling is required per job to avoid connection exhaustion and stale-connection errors after DB failover. Connection configuration is passed as raw arrays, which means settings will drift from the conventions the rest of the org documents.

Failure modes to instrument for.

• Composer resolution conflict blocking an unrelated dependency upgrade (most likely first symptom, and the one that costs the most engineering time).
• Class collision or dual-global-capsule state routing queries to the wrong connection.
• Hard failure on a PHP minor upgrade with no upstream fix available.
• Connection leak in CLI loops and long-running workers.
• Configuration drift from Laravel conventions, causing environment-specific incidents.

Recommendation. Do not adopt as a new dependency. Approve a time-boxed spike (one to two days) only to validate that Eloquent outside Laravel delivers value for the target codebase; if it does, depend on illuminate/database directly with a pinned version and the native Capsule\Manager. If the package is already present, schedule replacement within one to two sprints — the substitution is small and removes an unmaintained pin from the dependency graph. Success criteria for the spike: Eloquent models and migrations working against the target database in a non-Laravel context, a documented exit path, and a pinned, provenance-verified dependency.