README

Database abstraction layer for WordPress, on top of wpdb and dbDelta.

wpdb gives you direct SQL access, but that comes with tradeoffs. Dbal exists to improve:

Security by default. WordPress queries are unescaped unless you remember to call prepare() yourself - an opt-in safeguard that's easy to forget. Dbal escapes automatically, so secure queries are the default, not something you have to remember to do.
Typed results, not just strings. Because Dbal knows your schema, query results come back as the type your schema declares - a column defined as INT returns an actual int, a FLOAT column returns a float. No more casting results by hand just to get the type you already told the schema to expect.
Schema migrations without the pain. Creating - and especially upgrading - custom database tables in WordPress is notoriously painful, which is exactly why so many projects give up and cram everything into wp_posts instead. With Dbal you define your schema programmatically; when that definition changes, Dbal handles the upgrade for you.

New to Dbal?

Getting started - the best first stop: introduces the Dbal entry point and how the package is structured.
Learning by example - a complete, realistic walkthrough of defining a table and running the full range of CRUD operations.
Columns & Column - how to define table columns when building a schema.
Indexes & Index - how to define primary, unique, and regular indexes for a schema.
Schemas - how to implement InstallableSchema to create and upgrade custom database tables.
Querying - how to build safe, code-based queries and work with Result/ResultSet.
Error handling - the structured approach to handling query errors via Error, ErrorCollector, and PhpErrors.

Requirements

PHP >= 8.2
WordPress (with wpdb available)

To run the integration test suite locally, you'll also need the pdo_sqlite PHP extension - it powers the SQLite-backed WordPress environment composer tests:integration boots via syde/wp-phpunit-integration, no MySQL or Docker required.

Installation

composer require syde/dbal

Quick Start

use Syde\Dbal\Dbal;

// Select all events
$resultSet = Dbal::select('events')->all();

// Insert a record
$result = Dbal::writeOn('events')->insert([
    'post_id' => 1,
    'title'   => 'My Event',
    'status'  => 'SCHEDULED',
    'type'    => 'party',
]);

// Delete a record
Dbal::deleteFrom('events')->where(['id' => 1]);

Copyright and License

This package is free software distributed under the terms of the GNU General Public License version 2 or (at your option) any later version. For the full license, see LICENSE.

syde / dbal

Package info

Security

Statistics