README

Marwa DB is a framework-agnostic PHP database toolkit built on PDO. It provides connection management, a fluent query builder, an Active Record style ORM, schema helpers, migrations, seeders, a CLI, and lightweight debugging utilities for standalone apps or framework integrations.

Requirements

PHP 8.2 or newer
ext-pdo
ext-json
A supported database driver: MySQL, PostgreSQL, or SQLite

Installation

composer require memran/marwa-db

For development inside this repository:

composer install

Features

Connection pooling and retry handling
Fluent query builder with prepared statements
ORM with timestamps, casts, soft deletes, mass assignment control, and relations
Schema builder for create, alter, rename, and drop operations
Migration and seeder command support
Debug panel and query logging helpers

Quick Start

<?php

require __DIR__ . '/vendor/autoload.php';

use Marwa\DB\Bootstrap;
use Marwa\DB\Facades\DB;
use Marwa\DB\ORM\Model;
use Marwa\DB\Schema\Schema;

$config = require __DIR__ . '/config/database.php';

$manager = Bootstrap::init($config);

DB::setManager($manager);
Model::setConnectionManager($manager);
Schema::init($manager);

Usage Examples

Query Builder

$users = DB::table('users')
    ->select('id', 'email')
    ->where('status', '=', 'active')
    ->orderBy('id', 'desc')
    ->limit(10)
    ->get();

ORM

$user = App\Models\User::find(1);

if ($user !== null) {
    $user->email = 'new@example.com';
    $user->save();
}

Schema Builder

Schema::create('posts', static function ($table): void {
    $table->increments('id');
    $table->string('title');
    $table->text('body');
    $table->timestamps();
});

Seeders

use Marwa\DB\Seeder\SeedRunner;

$runner = new SeedRunner($manager);
$runner->runAll();

Configuration Guide

The package expects a connection array. The recommended shape is:

return [
    'default' => [
        'driver' => 'mysql',
        'host' => '127.0.0.1',
        'port' => 3306,
        'database' => 'app',
        'username' => 'root',
        'password' => '',
        'charset' => 'utf8mb4',
        'options' => [],
        'retry' => 3,
        'retry_delay' => 300,
        'debug' => false,
    ],
];

Supported keys:

driver
host
port
database
username
password
charset
options
retry
retry_delay
debug

SQLite example:

return [
    'default' => [
        'driver' => 'sqlite',
        'database' => __DIR__ . '/../database/app.sqlite',
        'debug' => false,
    ],
];

Legacy configuration shape is still supported:

return [
    'default' => 'sqlite',
    'connections' => [
        'sqlite' => [
            'driver' => 'sqlite',
            'database' => ':memory:',
        ],
    ],
];

Project Layout

src/ core library code
bin/marwa-db CLI entrypoint
config/database.php default connection config
database/migrations/ user migrations
database/seeders/ user seeders
tests/ unit and integration tests
example/ runnable examples

Testing

Run the full test suite:

composer test

Run unit tests only:

composer test:unit

Run integration tests:

MARWA_DB_INTEGRATION=1 composer test:integration

Run coverage output:

composer test:coverage

This requires Xdebug or another supported coverage driver.

Static Analysis

Run PHPStan with the repository configuration:

composer analyse

composer analyze is kept as an alias for compatibility.

Linting

Run the built-in PHP syntax check across tracked PHP files:

composer lint

CLI

Inspect available commands:

php bin/marwa-db list

CI/CD

The repository is intended to run in GitHub Actions with a simple quality gate:

composer lint
composer analyse
composer test

The workflow can also run coverage on a dedicated job or matrix entry.

Security Notes

Do not commit real credentials to config/database.php.
Prefer environment-specific config loading in production.
Keep migration and seeder code under source control, but never hard-code secrets into them.
Use prepared statements for user input; the query builder already binds values for normal where, insert, update, and delete flows.

Contribution Guide

Create a focused branch.
Add or update tests for behavior changes.
Run composer lint, composer analyse, and composer test.
Keep public API changes documented in this README.
Use short imperative commit messages such as Fix query builder state leaks.

License

MIT. See LICENSE.

memran / marwa-db

Maintainers

Package info

Statistics

Security