Download the PHP package alejoluc/lazypdo without Composer

alejoluc\LazyPDO

Contents

1. Installation
2. On Connection Errors
3. Usage
4. On Dependency Injection Containers

This package provides a drop-in replacement for PHP's native PDO class.

The LazyPDO class is lazy in the sense that, unlike native PDO, it will not attempt to connect to the database server upon instantiation. Instead, it will store all the connection details and wait until it actually needs a connection, for example, to execute a query.

This is useful if you have an effective caching mechanism in place, and the database may not need to respond to all requests.

LazyPDO extends PDO, so any instance of LazyPDO is an instance of PDO. That means you can pass along an instance of LazyPDO anywhere a PDO instance is expected.

Installation

Option A) From the command line

composer require alejoluc/lazypdo:*

Option B) Add the dependency in the "require" section of composer.json, then run composer installor composer update, as needed

On Connection errors

Before getting into usage details, one thing you have to consider is connection errors. In PHP's native PDO, the connection error would be raised as soon as you try to instantiate the class with a bad connection string, or with credentials rejected by the database server. A simple try/catch construct around PDO's instantiation is sufficient in that case. However, since this class is "lazy" and delays the connection until it needs it, this means the connection error could be raised anywhere in your code (that is, upon the first call of a method that requires a connection to be established). To avoid having to wrap every database call inside try/catch blocks (as long as you are not using PDO::ERRMODE_EXCEPTION), you can use the onConnectionError() method to specify a callback to handle a potential PDOException upon connection. Any callable can be passed to the onConnectionError() method, not just functions, so $lazypdo->onConnectionError([$myErrorHandler, 'handle']); is also valid. An example with a function instead:

However, many applications have a top-level try/catch, or they have custom error handling. So, by default, if you do not specify a callback, LazyPDO will just bubble up the exception until it is (hopefully) catched and handled properly.

Usage

LazyPDO can be used as you would use PDO. If you know PDO, you know LazyPDO. Simple as that. Here are some examples to refresh the mind. Note that you can access the constants from either PDO or LazyPDO, and you can intermingle them, but why do that? Just stick with PDO::* constants to make it clear that they are interoperable.

With PDO::ERRMODE as ERRMODE_SILENT (default PDO behavior)

With ERR_MODE as ERRMODE_EXCEPTION, the recommended behavior, or so it was a week or two ago

Again, if you have an application level try/catch, or a custom error handler that catches all errors and exceptions, which you probably should, the try/catch construct is unnecessary.

Why not use a Dependency Injection Container instead?

You can, and you can put LazyPDO into it. But if you want to use native PDO, you could also get the lazy behavior by using a DIC, as long as you never pass the PDO key directly and pass the container instead (in which case, it's not a DIC, it's a Service Locator, which some people consider an anti-pattern that should be avoided, but not all of them). If you do pass the PDO key directly, however, you do not get the same behavior as with LazyPDO, because when you access a member in a DIC, the DIC will most likely instantiate what it contains in said key. Consider Pimple, which by the way I think is great.

To make sure native PDO is not instantiated unless necessary, the function and the call should be refactored to something like this:

However, if instead of PDO you are using LazyPDO inside the DIC, in any of the previous two code examples the database connection will not be established unless the cached data cannot be found. Let's see the first example again, but with LazyPDO instead: