Laravel Database Mock Laravel Package

Product Decisions This Supports

• Build vs. buy for test infrastructure: Avoid spending engineering time building an internal PDO-mocking layer. This package is a low-cost candidate to evaluate for a narrow, high-value “SQL contract” test tier—especially for repositories, reporting queries, billing flows, and write paths.
• Release confidence for data-heavy features: Lets teams assert the exact queries a feature emits and the rows it hydrates without provisioning a database. Useful when deciding whether a query-heavy feature is ready to ship or needs deeper integration coverage.
• Read/write replica readiness: The mockEachPdo() reader/writer split is the strongest product differentiator. It lets teams assert routing intent before replica infrastructure exists, de-risking a common production bug class that single-database SQLite tests cannot catch.
• Test strategy and CI cost trade-offs: Supports a deliberate tiering decision—keep real-database integration tests for behavior, use PDO mocking for query shape and routing—rather than converting the whole suite.
• Prioritizing quality investments: If the roadmap includes scaling reads, sharding-adjacent work, or query-builder refactors, this package can make the expected SQL contract explicit and reviewable.
• Risk management for vendor/tooling bets: With 6 stars, 0 dependents, and alpha releases, this is not a standardize-now decision. It supports a time-boxed spike with clear exit criteria, not a platform commitment.
• Onboarding and specification value: Tests written against it document expected queries, bindings, and hydration behavior—useful when handing off repositories or auditing query changes.

When to Consider This Package

Consider it when:

• The team is on PHP ^8.2 and Laravel 11–14, already uses Mockery, and can accept an alpha transitive dependency (mpyw/mockery-pdo).
• You need a small, dedicated SQL-contract test tier—not a replacement for RefreshDatabase or real integration tests.
• Query assertions matter: reporting, exports, billing, data synchronization, or write paths where the generated SQL and bindings are part of the contract.
• Read/write replica routing is on the roadmap or already configured, and you want to test routing without standing up topology.
• CI should run without a database for a specific class of tests, or database-backed environments are slow/expensive.
• Engineering is willing to pin the alpha exactly, commit the lockfile, and own SQL snapshot maintenance.
• The test connection uses the same grammar as the assertions—e.g., MySQL backticks for MySQL-style SQL.

Look elsewhere when:

• You need real database behavior: constraints, foreign keys, cascades, triggers, generated columns, collation, isolation, or realistic transaction semantics.
• The suite is Pest-native and the team wants fake()/expect() ergonomics; this API is Mockery-shaped.
• The organization requires stable, production-supported dependencies or avoids alpha packages.
• You need broad suite conversion; the strict, ordered expectations and SQL-text coupling make that a poor trade.
• Data stores are non-PDO (Redis, MongoDB) or query-builder-only paths with nothing to intercept.
• Portability across MySQL, Postgres, and SQLite is required in the same test suite; generated SQL text will diverge by grammar.
• Low adoption signals are disqualifying for your risk appetite: single-maintainer, experimental, 0 dependents, pre-1.0 API.

How to Pitch It (Stakeholders)

For executives: This is not a platform bet or a production dependency. It is a reversible, dev-only experiment to improve confidence in data-heavy releases and to validate read/write replica routing before infrastructure investment. The cost is small—one dev dependency, no runtime footprint, MIT license—but the package is experimental and lightly adopted, so we should approve a time-boxed spike, not standardization.

For engineering: The package mocks the PDO layer beneath Laravel connections, so Eloquent hydration, casts, timestamps, and collections still run. That makes it stronger than stubbing models and cheaper than provisioning databases for query-shape tests. Its standout capability is asserting reader/writer routing. The trade-off is strict, ordered query expectations and SQL strings bound to the configured grammar—so keep the tier small, name tests after query intent, and do not let it replace real integration coverage.

Decision requested: Approve a short evaluation with explicit exit criteria: prove one repository/query object, prove replica routing, and measure maintenance friction. If the alpha API churn or SQL snapshot burden outweighs the value, drop it without further investment.