Download the PHP package xalaida/pdo-mock without Composer

PDOMock

PDOMock is a PHP library for testing database interactions without relying on an actual database connection.

Unlike higher-level abstractions like the repository pattern, PDOMock validates database queries at the SQL level, providing greater control and insights into query execution.

This testing technique dramatically accelerates test suite performance and helps identify common issues such as N+1 queries.

Mainly inspired by the Go library SQL-mock.

🔍 Overview

• Supports any SQL dialect
• Supports most PDO features
• Works with most popular ORMs
• PHPUnit integration
• Supports all PHP versions from 5.6
• No dependencies

🚀 Installation

Install the library using Composer:

📽️ Example Usage

Here’s an example of how to use PDOMock in your test cases. Let's assume we have the following service that interacts with the database via PDO:

Now, we can write a test for this service:

🧾 Documentation

Query Expectation

PDOMock requires that you set up expectations for each query. To define a simple query expectation, use the expect method:

By default, queries are validated by an exact string match. However, if the query is written in a different format (e.g., multiline), the test will fail. To allow for more flexibility, you can use toMatchRegex:

This will match the query regardless of whitespace formatting:

And also allows to provide regex placeholders if you want to skip some parts of the query:

Note: Be cautious when using toMatchRegex as it will also strip whitespace from quoted values.

For "write" queries, it's recommended to use a strict query comparator.

Keep in mind that the query comparator does not use any SQL parsers, so you should manually verify that all queries are valid SQL.

The expect method works with any PDO method, including exec, query, or prepared statements. To verify that a statement was prepared, you can specify this manually:

Parameters Validation

You can validate query parameters using the with method, which allows you to pass an array of parameter values and types:

For anonymous placeholders (?), use this syntax:

You can also specify the parameter types:

By default, parameters are validated using a strict comparator that checks both values and types. For a looser comparison, you can use toMatchParamsLoosely:

This will pass even if the value is cast to a different type (e.g., '7' instead of 7).

Alternatively, use toMatchParamsNaturally to allow automatic type matching:

For manual validation, you can use a callback:

Validation fails only if the callback returns false. Additionally, the $params and $types arrays use a 1-based index, consistent with PDO bind functions.

Result Set Simulation

To simulate query results, use the willFetch method:

For more complex result sets, you can use a ResultSet instance:

Insert, Update, Delete Queries

For insert queries, specify the insert ID:

After execution, the $pdo->lastInsertId() method will return 7.

For update and delete queries, you can specify the number of affected rows:

Transaction Management

You can verify transaction behavior with the following methods: expectBeginTransaction, expectCommit, and expectRollback. Here's an example:

Error Simulation

To simulate query exceptions, use the willFail method:

Post-Execution Assertions

To verify that all expected queries were executed, use assertExpectationFulfilled:

Default Comparators

You can set default comparators that will apply to all future queries:

Integration with PHPUnit

If you're using PHPUnit, you may want to integrate its assertion mechanism with PDOMock. To do so, register the extension in your PHPUnit configuration file:

Alternatively, you can manually configure it in your TestCase class:

📜 License

The MIT License (MIT). Please see LICENSE for more information.