Download the PHP package apigopro/slim-database without Composer

apigopro/slim-database

Lazy PDO database connection management for Slim Framework 4, requiring PHP 8.5.

Supports PostgreSQL, MySQL/MariaDB, and Oracle through one consistent API. Built around a dual-credential pattern: separate, distinctly-typed connections for authentication data vs. the rest of the application, so least-privilege database roles are enforced both by Postgres/MySQL/ Oracle GRANTs and by PHP's type system (you can't accidentally inject the wrong connection into the wrong place without it being visible in the constructor signature).

Install

Published on Packagist

Requirements

• PHP 8.5
• The pdo extension (always required)
• One driver-specific PDO extension, matching whichever database you actually use:
  • pdo_pgsql for PostgreSQL
  • pdo_mysql for MySQL/MariaDB
  • pdo_oci for Oracle (see below — this one needs manual setup, not a package manager)
• vlucas/phpdotenv if you're loading config from a .env file rather than real process environment variables
• A PSR-11 DI container (this README uses PHP-DI) — not strictly required by this package's code, but the intended usage pattern relies on one for wiring things together

PostgreSQL

MySQL / MariaDB

Named timezones require a one-time setup step. MySQL doesn't ship with timezone data loaded by default — connecting with DB_TIMEZONE=Europe/Sarajevo (or any named zone) fails with Unknown or incorrect time zone until you load it once per server:

This is a MySQL server-level gotcha, not something this package can work around — it affects any application connecting with a named timezone, not just this one.

Oracle

This is the one that isn't a simple package-manager install — Oracle requires a licensed manual download, no apt/pecl one-liner can fetch it.

1. Create a free Oracle account and download Instant Client Basic and Instant Client SDK for your platform from Oracle's site (search "Oracle Instant Client downloads" — the exact URL path changes over Oracle's site restructures often enough that it's not worth hardcoding here).

2. Extract and register the shared libraries:

   (adjust the instantclient_21_1 directory name to whatever version you actually downloaded)

3. Install build tools and the PECL extensions:

   pdo_oci has, at different points in PHP's history, shipped bundled and also existed as a separate PECL package — check what's actually available for your PHP version before assuming either way:

   Typical PECL install, pointing at your Instant Client directory:

   For non-interactive installs:

4. Enable the extension(s) in php.ini (or a file under conf.d/):

   Then restart PHP-FPM:

5. Verify:

I wasn't able to test the Oracle path against a real server while building this package — Oracle's download requires accepting their license through a browser session, which isn't something available in an automated environment. Everything else in this README (PostgreSQL, MySQL, the DSN templating, the connection classes themselves) was verified against real running servers. If you hit something that doesn't match reality during Oracle setup, it's worth double-checking against Oracle's current official docs for your specific Instant Client version.

How the DSN template works

DatabaseCredentials->dns is a printf-style template. AbstractDatabaseConnection builds the final DSN with:

So whatever you put in DB_DNS must have exactly three placeholders, in that order: host, port, name. Examples per driver are in .env.example. If your DSN ever needs a literal % character for some other reason, escape it as %%.

.env setup

Copy .env.example to .env and fill in real values — pick exactly one driver block (Postgres, MySQL, or Oracle) and leave the others commented out. DB_DNS and DB_ENCODING are only meant to be set once; if more than one block is active, later values silently overwrite earlier ones in the same .env file (dotenv doesn't merge repeated keys).

Load it early in your bootstrap, before building your container:

The two-connection pattern

DatabaseConfiguration reads two separate sets of credentials from your env — DB_AUTH_USER/ DB_AUTH_PASSWORD and DB_APP_USER/DB_APP_PASSWORD — sharing the same host/port/database name. The intended setup is two actual database roles with different grants:

AuthDatabaseConnection and AppDatabaseConnection are distinct PHP classes (both extending AbstractDatabaseConnection), not just two instances of the same class — so a constructor type-hint like AuthDatabaseConnection $db is self-documenting, and using the wrong one is a visible mistake in code, on top of the database itself enforcing the real boundary via GRANTs.

Wiring into a DI container (PHP-DI example)

Wiring the closing middleware

Add it first, before any other middleware, so it's the outermost layer — Slim's middleware stack is nested, and the first middleware added is the last to finish on the way out, which is what guarantees the connections close only after the route handler and every other middleware have fully completed:

Usage in an action class

DatabaseCredentials reference

Design notes

• PDO::ATTR_ORACLE_NULLS is applied unconditionally, for every driver. Despite the name, this isn't Oracle-specific — it converts empty strings to NULL on fetch, for whichever driver is active. If your Postgres/MySQL tables rely on distinguishing an empty string from NULL, this default may not be what you want; it's currently not configurable per-connection.
• Connections are lazy. Nothing connects to the database until ->get() is actually called, so injecting these classes broadly (even into code paths that never touch the DB) costs nothing.
• close() has no effect on connections referenced elsewhere. If ->get()'s return value gets stashed in another variable/property, that reference keeps the connection alive regardless of calling close() on the wrapper — PDO has no real close() method, only "destroy every reference and let PHP's refcounting close it."
• Persistent connections (DB_PERSISTENT=true) get pooled/reused by PHP across requests on the same worker rather than truly closing — useful under load, but every long-lived worker holding a persistent connection open adds up against your database's connection limit. Left off by default.

Testing

The included tests cover connection lifecycle (get()/close()/isConnected()), the DatabaseConfiguration env-var parsing, and the closing middleware's success/exception paths against a real PostgreSQL instance. MySQL's session-configuration SQL was independently verified against a live MySQL 8.0 server during development (including the named-timezone table dependency noted above). Oracle's SQL/DSN construction was checked for correctness but not run against a live Oracle instance — see "Oracle setup" above for why.

License

MIT.