README

Safe $wpdb wrapper with fluent query builder for the WPZylos framework.

📖 Full Documentation | 🐛 Report Issues

✨ Features

• Connection Class — Plugin-scoped $wpdb wrapper with 21 public methods
• Query Builder — Fluent chainable interface for SELECT, INSERT, UPDATE, DELETE
• Automatic Preparation — All queries use $wpdb->prepare() internally
• Plugin-Scoped Table Names — Automatic prefix handling via ContextInterface
• Transaction Support — Automatic and manual transaction management with rollback
• CRUD Convenience — find(), insertGetId(), and direct table methods
• Error Inspection — hasError(), lastError(), rowsAffected()
• Raw Query Access — query(), getRow(), getResults(), getVar()

📋 Requirements

🚀 Installation

composer require KYNetCode/wpzylos-database

⚙️ Service Provider Registration

Register DatabaseServiceProvider in your plugin's service providers:

use WPZylos\Framework\Database\DatabaseServiceProvider;

// In your plugin's boot configuration
'providers' => [
    DatabaseServiceProvider::class,
],

This registers two singleton bindings:

📖 Quick Start

use WPZylos\Framework\Database\Connection;

// Resolve from container
$db = $app->make(Connection::class);
// or
$db = $app->make('db');

// Fluent queries via QueryBuilder
$users = $db->table('users')->get();
$user  = $db->table('users')->where('id', 1)->first();

🏗️ Core Usage

Select Queries

// Get all records
$users = $db->table('users')->get();

// Get first record
$user = $db->table('users')->where('email', $email)->first();

// Select specific columns
$names = $db->table('users')->select('id', 'name')->get();

// With conditions
$active = $db->table('users')
    ->where('status', 'active')
    ->where('role', 'admin')
    ->get();

// Comparison operators
$expensive = $db->table('products')
    ->where('price', '>', 100)
    ->orderBy('price', 'DESC')
    ->limit(10)
    ->get();

// Where IN
$selected = $db->table('users')
    ->whereIn('id', [1, 2, 3])
    ->get();

// Count
$total = $db->table('users')
    ->where('status', 'active')
    ->count();

Insert

// Via QueryBuilder — returns insert ID or false
$id = $db->table('users')->insert([
    'name' => 'John Doe',
    'email' => 'john@example.com',
]);

Update

$affected = $db->table('users')
    ->where('id', 1)
    ->update(['status' => 'inactive']);

Delete

$affected = $db->table('users')
    ->where('id', 1)
    ->delete();

Find by Primary Key

// Uses Connection::find() directly (requires full table name)
$user = $db->find('wp_myplugin_users', 1);

// Custom primary key column
$item = $db->find('wp_myplugin_items', 'abc-123', 'uuid');

Insert and Get ID

// Uses Connection::insertGetId() directly (requires full table name)
$id = $db->insertGetId('wp_myplugin_users', [
    'name' => 'Jane Doe',
    'email' => 'jane@example.com',
]);

🔒 Transactions

Automatic (Recommended)

$orderId = $db->transaction(function () use ($db, $orderData, $paymentData) {
    $orderId = $db->table('orders')->insert($orderData);

    $db->table('payments')->insert([
        'order_id' => $orderId,
        ...$paymentData,
    ]);

    return $orderId;
});

Manual

$db->beginTransaction();

try {
    $db->table('orders')->insert($order);
    $db->table('inventory')
        ->where('product_id', $productId)
        ->update(['stock' => $newStock]);

    $db->commit();
} catch (\Throwable $e) {
    $db->rollback();
    throw $e;
}

🔍 Raw Queries

All raw methods use $wpdb->prepare() when arguments are provided:

// Execute raw SQL
$db->query("UPDATE `{$table}` SET views = views + 1 WHERE id = %d", $id);

// Get a single row
$user = $db->getRow("SELECT * FROM `{$table}` WHERE email = %s", $email);

// Get multiple rows
$logs = $db->getResults("SELECT * FROM `{$table}` WHERE level = %s", 'error');

// Get a single value
$count = $db->getVar("SELECT COUNT(*) FROM `{$table}` WHERE status = %s", 'active');

🛠️ Error Handling

$db->table('users')->insert($data);

if ($db->hasError()) {
    $error = $db->lastError();  // Error message string
}

$affected = $db->rowsAffected();
$lastId = $db->lastInsertId();

📦 Related Packages

📖 Documentation

• Usage Guide — Patterns, workflows, and examples
• API Reference — Complete class and method documentation
• Full Documentation — Online docs and tutorials

☕ Support the Project

• GitHub Sponsors
• PayPal Donate

📄 License

MIT License. See LICENSE for details.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Made with ❤️ by KYNetCode