Dbwrapper Laravel Package

Technical Evaluation

Architecture fit. soluble/dbwrapper is a framework-agnostic, minimalist PDO abstraction (multi-driver: MySQL/PostgreSQL/SQLite/SQL Server) with a thin, procedural-style API. It has no Laravel idioms: no ServiceProvider, no Facade, no publishable config, no Eloquent or Query Builder integration, no migration/transaction helpers aligned with Laravel's contracts. Inside a Laravel application this creates a parallel data-access path alongside Illuminate\Database, which is an architectural anti-pattern: two connection lifecycles, two error-handling models, two logging surfaces, and two mental models for engineers. Its legitimate fit is narrow — a bounded legacy module, a CLI/worker, or a non-Laravel microservice sharing a monorepo.

Integration feasibility. Composer-installable, MIT-licensed, small surface area — mechanically easy to require. The blockers are non-mechanical:

• Platform constraint risk: a 2019-era release almost certainly declares php: ^7.x. Laravel 10/11 require PHP 8.1/8.2+, so composer require will likely fail resolution. Adoption realistically means forking to relax the PHP constraint and adding PHP 8 return types/deprecation fixes.
• No configuration bridge: someone must map config/database.php credentials/driver options into the wrapper's config object and register a singleton with correct lifecycle semantics.
• No first-class support for long-running workers (Octane, Swoole, queue daemons): reconnect/stale-connection behavior must be proven, not assumed.

Technical risk. Rated Low quality (score 0.135) with 7 stars and 0 dependents: essentially zero ecosystem validation and a single-maintainer bus factor. Last release January 2019 means no PHP 8 hardening, no security patch cadence, and no upstream responsiveness to a CVE. Countervailing: the dependency chain is shallow (PDO/Doctrine DBAL) and PDO semantics are stable, so runtime risk is moderate rather than severe — the dominant risk is abandonment, i.e., we inherit maintenance. Test coverage and CI matrix are unverifiable from the outside; treat as untested on our runtime until proven.

Key questions.

1. What concrete capability does this give us that DB::connection()->getPdo() or a ~150-line internal PDO wrapper does not?
2. Does it install and pass tests on PHP 8.1–8.3 and our Laravel version, unmodified?
3. Does the app already depend on Doctrine DBAL (version-conflict check)?
4. Are we prepared to fork, own, and CI it — and who is the named owner?
5. Does it handle named/positional parameter binding and nested transactions consistently across our target drivers?
6. Is it safe under persistent connections (Octane/queue workers), and how do we observe queries for logging/tracing?

Integration Approach

Stack fit. Poor as a primary data layer; acceptable only as an isolated adapter behind an internal contract. Recommendation: do not adopt as a general dependency. If a specific legacy component needs it, confine it to one bounded context and forbid its use in new code via a lint/review rule.

Migration path. Interface-first, exit-first:

1. Define our own DatabaseAdapter contract (query, fetch, insert/update/delete, transaction).
2. Implement it over soluble/dbwrapper and over Laravel's DB facade, so the wrapper is swappable by config.
3. Bind the chosen implementation in a ServiceProvider; map config/database.php into the wrapper's config DTO.
4. Add integration tests against every driver we actually run (not the full matrix — cost without value).
5. Document the ADR: why it exists, and the trigger conditions for removal.

Compatibility. Pin an exact version; if forking, tag an internal 1.x-internal and register it as a VCS/private path repository. Verify ext-pdo plus the specific driver extensions in our base images. Check Doctrine DBAL version alignment against the rest of the lockfile before committing — this is the most likely silent conflict.

Sequencing (≈2 weeks elapsed, ~5–7 engineer-days).

1. Day 1–2: PoC install on a throwaway branch; confirm PHP/Laravel compatibility or confirm the need to fork.
2. Day 2–3: Source/security read-through of the (small) codebase; license and transitive dependency review.
3. Day 3–5: Fork, add PHP 8 CI matrix, static analysis, and a smoke test suite.
4. Day 5–7: Build the adapter + tests; wire the service provider.
5. Week 2: Pilot in one low-risk module; collect query logging and error-rate data.
6. Decision gate: expand, freeze, or retire in favor of the internal wrapper.

Operational Impact

Maintenance. Effectively unmaintained upstream — the moment we ship it, we own it. Budget a named owner and roughly 10–15% of one engineer's capacity for PHP upgrades, dependency bumps, and security triage. Without a fork and CI, the package will silently fail the next PHP minor upgrade. Compare cost honestly: a fork + CI + audit is ~3–5 engineer-days; an internal PDO wrapper with full ownership is ~2–3 days. The wrapper is usually the cheaper path.

Support. No vendor, no community (7 stars, 0 dependents), documentation limited to a README and a stale docs site. All support is internal L1/L2. Onboarding friction is real: new engineers know Laravel's DB layer, not this, so every incident in that module has a slower first responder. Mitigate with a short runbook and a "do not extend" banner in the README.

Scaling. Throughput is essentially PDO throughput — no ORM overhead, so raw performance is fine and not a concern. What's absent is everything around the query: no connection pooling, read/write splitting, lazy connections, retry/backoff, or query instrumentation. Those must be layered by us or accepted as gaps. Under Octane/queue workers, unproven reconnect behavior is the main scaling hazard.

Failure modes.

• Hard break on PHP minor/major upgrade (no upstream patch).
• Driver-specific parameter-binding divergences surfacing only in production on a non-primary driver.
• Transaction edge cases: savepoints, nested transactions, and rollback-on-exception semantics differing from Laravel's expectations.
• Errors bypassing Laravel's exception handler and reporting pipeline → degraded observability.
• No query listener → slow-query visibility lost unless manually wired.
• Connection leakage/staleness in long-running processes.

Ramp-up. The API surface is small: a mid-level PHP developer is productive in ~1–2 days. Budget an additional sprint-equivalent of edge-case hardening and test-writing, because the risk here is not learning the API — it's discovering undocumented behavior in production.