95 lines
3.3 KiB
Markdown
95 lines
3.3 KiB
Markdown
|
# Database Module
|
||
|
|
|
||
|
|
A static wrapper around WordPress's `$wpdb` global that provides a unified interface with consistent error handling.
|
||
|
|
|
||
|
|
**Namespace:** `Reservair\Database`
|
||
|
|
|
||
|
|
## Why
|
||
|
|
|
||
|
|
Direct `$wpdb` usage has two problems: error handling is manual (check `$wpdb->last_error` after every call) and the API is inconsistent (`insert` returns `false|int`, `get_results` returns `null|array`, etc.). `Db` normalises this — all failures throw `DbException`, all collection methods return `array`, and `insert` returns the new row's ID directly.
|
||
|
|
|
||
|
|
The namespace also prevents conflicts with any other plugin that might define a `Db` class in the global scope.
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
```php
|
||
|
|
use Reservair\Database\Db;
|
||
|
|
use Reservair\Database\DbException;
|
||
|
|
|
||
|
|
// SELECT — single row
|
||
|
|
$row = Db::get_row('SELECT * FROM %i WHERE id = %d', [$table, $id], ARRAY_A);
|
||
|
|
|
||
|
|
// SELECT — multiple rows
|
||
|
|
$rows = Db::get_results('SELECT * FROM %i WHERE status = %s', [$table, 'active']);
|
||
|
|
|
||
|
|
// SELECT — scalar value
|
||
|
|
$count = Db::get_var('SELECT COUNT(*) FROM %i', [$table]);
|
||
|
|
|
||
|
|
// SELECT — single column
|
||
|
|
$ids = Db::get_col('SELECT id FROM %i WHERE active = 1', [$table]);
|
||
|
|
|
||
|
|
// INSERT — returns new row ID
|
||
|
|
$id = Db::insert(Db::prefix() . 'rsv_reservations', ['name' => 'Alice', 'seats' => 2]);
|
||
|
|
|
||
|
|
// UPDATE — returns number of rows affected
|
||
|
|
$affected = Db::update(Db::prefix() . 'rsv_reservations', ['seats' => 3], ['id' => $id]);
|
||
|
|
|
||
|
|
// DELETE — returns number of rows deleted
|
||
|
|
$deleted = Db::delete(Db::prefix() . 'rsv_reservations', ['id' => $id]);
|
||
|
|
|
||
|
|
// Raw query (DDL, transactions, etc.)
|
||
|
|
Db::query('ALTER TABLE %i ADD COLUMN notes TEXT', [$table]);
|
||
|
|
|
||
|
|
// Transactions
|
||
|
|
try {
|
||
|
|
Db::begin_transaction();
|
||
|
|
Db::insert(...);
|
||
|
|
Db::update(...);
|
||
|
|
Db::commit();
|
||
|
|
} catch (DbException $e) {
|
||
|
|
Db::rollback();
|
||
|
|
throw $e;
|
||
|
|
}
|
||
|
|
|
||
|
|
// Helpers
|
||
|
|
$prefix = Db::prefix(); // e.g. "wp_"
|
||
|
|
$lastId = Db::last_insert_id();
|
||
|
|
$charsetCollate = Db::charset_collate(); // e.g. "DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci"
|
||
|
|
```
|
||
|
|
|
||
|
|
## Error handling
|
||
|
|
|
||
|
|
Every method throws `DbException` (extends `\RuntimeException`) on failure. You do not need to check `$wpdb->last_error` manually.
|
||
|
|
|
||
|
|
```php
|
||
|
|
use Reservair\Database\Db;
|
||
|
|
use Reservair\Database\DbException;
|
||
|
|
|
||
|
|
try {
|
||
|
|
Db::insert(Db::prefix() . 'rsv_reservations', $data);
|
||
|
|
} catch (DbException $e) {
|
||
|
|
// $e->getMessage() contains the $wpdb error string
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## API reference
|
||
|
|
|
||
|
|
| Method | Returns | Notes |
|
||
|
|
|---|---|---|
|
||
|
|
| `Db::query(sql, params)` | `int` — rows affected | Use for DDL and raw DML |
|
||
|
|
| `Db::get_row(sql, params, output)` | `object\|array\|null` | `null` = no match |
|
||
|
|
| `Db::get_results(sql, params, output)` | `array` | Empty array when no rows |
|
||
|
|
| `Db::get_var(sql, params)` | `?string` | `null` = no match |
|
||
|
|
| `Db::get_col(sql, params)` | `array` | Empty array when no rows |
|
||
|
|
| `Db::insert(table, data, format)` | `int` — new row ID | |
|
||
|
|
| `Db::update(table, data, where, format, where_format)` | `int` — rows affected | |
|
||
|
|
| `Db::delete(table, where, where_format)` | `int` — rows deleted | |
|
||
|
|
| `Db::begin_transaction()` | `void` | |
|
||
|
|
| `Db::commit()` | `void` | |
|
||
|
|
| `Db::rollback()` | `void` | |
|
||
|
|
| `Db::prefix()` | `string` | e.g. `"wp_"` |
|
||
|
|
| `Db::last_insert_id()` | `int` | |
|
||
|
|
| `Db::charset_collate()` | `string` | Use in `CREATE TABLE` DDL |
|
||
|
|
|
||
|
|
All `sql` parameters are passed through `$wpdb->prepare()` when `params` is non-empty.
|