Download the PHP package echo-fusion/databasemanager without Composer

DatabaseManager

DatabaseManager is a small, readable database layer for the EchoFusion framework. It is built to be replaced: your code talks to a tiny contract, and the implementation behind it can be our PDO connection, Doctrine DBAL, or anything else you write, chosen in configuration.

It is also meant to show what happens behind the scenes: the whole package is a few hundred lines you can read in an afternoon.

Part of EchoFusion, a modular PHP framework built from small packages.

Installation

Requirements

• PHP 8.1, 8.2 or 8.3
• ext-pdo (and the PDO driver you use: pdo_mysql, pdo_pgsql or pdo_sqlite)

Quick start

The contract

EchoFusion\Contracts\DatabaseManager\ConnectionInterface:

DatabaseManagerInterface adds connection(?string $name), has() and getDefaultConnectionName().

Parameters

• Values are always bound, never put into the SQL string. PHP types map to PDO types (int, bool, null, string).
• Use named (:id) or positional (?) placeholders.
• An array bound to a named placeholder expands to a list: WHERE id IN (:ids) with ['ids' => [1, 2, 3]] becomes IN (:ids_0, :ids_1, :ids_2). An empty array becomes IN (NULL), which matches nothing. (A :name inside a quoted SQL string is replaced too, so keep such literals out of queries that bind arrays.)

Transactions

Transactions nest. The outermost one is a real transaction; inner ones are savepoints, so an inner failure that you catch rolls back only the inner part:

Errors

A failed statement throws EchoFusion\DatabaseManager\Exceptions\QueryException, which carries the SQL (getSql()) and the original exception, but never the bound values (they may be secrets). All exceptions extend DatabaseException.

Query builder

A small fluent builder that works on any ConnectionInterface, so it keeps working if you swap PDO for Doctrine.

Safety built in:

• Table and column names are validated (letters, digits, _ and dots) and quoted, so they cannot carry SQL.
• Operators and order directions are whitelisted. Values are always bound.
• update() and delete() refuse to run without a WHERE clause. If you really mean every row: ->whereRaw('1 = 1').
• whereRaw($sql, $bindings) and selectRaw($sql) are the escape hatches; their SQL is used as written, so never put user input into it.

Configuration

Extra PDO attributes go in 'options' => [...]; use 'dsn' => '...' instead of the individual parts when you need an exact DSN. PDO is created with exceptions on, associative fetch mode and real prepared statements. SQLite connections enforce FOREIGN KEY constraints (including ON DELETE CASCADE), which SQLite itself leaves off by default; set 'foreign_keys' => false on a connection to turn that off.

Replacing the implementation

With Doctrine DBAL

Everything written against ConnectionInterface (including the query builder) works the same. The test suite proves it: one shared set of behaviour tests runs against both PdoConnection and DoctrineConnection.

With any other ORM or library

Implement ConnectionInterface (about ten small methods) in a class that takes the connection definition array, and reference it with 'class'. Run the shared behaviour tests (tests/ConnectionContractTestCase.php) against it to check you kept the contract. For example, an adapter around Eloquent's or Cycle's connection can forward fetchAll, execute and the transaction methods one to one.

Behind the scenes

• Lazy: the PDO object is created on the first query, so configuring ten connections costs nothing until one is used.
• Typed binding: each value is bound with the PDO type of its PHP type, so LIMIT ? and integer comparisons behave the same on every database.
• Savepoints: nesting counts levels; level 0 uses BEGIN, deeper levels use SAVEPOINT ef_sp_N.
• List expansion: ParameterExpander rewrites :ids into :ids_0, :ids_1, ... before preparing the statement.

Service provider

EchoFusion\DatabaseManager\Providers\DatabaseManagerProvider registers DatabaseManagerInterface and ConnectionInterface (the default connection) in a container, and configures the manager from the database section of your configuration on boot().

Testing

Credits

• Amir Shadanfar

License

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