README

Quma is a no-ORM database library for PHP. You store SQL in files, group those files in folders, and execute them through a small PDO-backed API. Quma also ships with template queries and a migration runner.

Requirements

Quma currently requires:

PHP 8.5 or newer
ext-json
ext-pdo
ext-readline

Install

composer require celema/quma

Quickstart

Create a SQL directory structure like this:

sql/
  users/
    byId.sql
    list.sql

Add a query file:

SELECT id, email FROM users WHERE id = ?;

Then configure Quma and run the query:

<?php

declare(strict_types=1);

use Celema\Quma\Connection;
use Celema\Quma\Database;

$conn = new Connection(
    'sqlite:' . __DIR__ . '/app.sqlite',
    __DIR__ . '/sql',
)->migrations(__DIR__ . '/migrations');

$db = new Database($conn);

$user = $db->users->byId(1)->one();
$users = $db->users->list()->all();

Quma maps directories to properties and files to methods:

sql/users/byId.sql becomes $db->users->byId()
sql/users/list.sql becomes $db->users->list()

What Quma provides

SQL-file based queries with positional or named parameters
explicit static /*:name:*/ placeholders for trusted driver-aware configuration fragments
PDO-backed execution with exact one(), stable first(), cursor-style fetch(), all(), lazy(), run(), and len()
optional row hydration into typed objects
PHP-powered SQL templates via .tpql files
multiple SQL directories with driver-specific overrides
migration commands for .sql, .tpql, and .php migrations
environment-controlled debug output for translated and interpolated SQL

Documentation

Start with the docs in docs/index.md.

Recommended pages:

Testing

Quma runs against SQLite by default and can also run against MySQL and PostgreSQL when you provide test databases.

composer test
composer test:sqlite
composer test:mysql
composer test:pgsql
composer test:all

For database setup and environment variables, see docs/testing.md.

Mutation testing

Mutation testing with Infection is not part of composer ci, but the CI workflow runs it after the coverage step against all three drivers and enforces the minimum mutation score from infection.json5.dist. Pushes only mutate the changed lines; a weekly scheduled run covers the whole codebase. Run it locally with:

composer mutation

It runs one PHPUnit process at a time because the tests share their SQLite files, migration fixtures, and MySQL/PostgreSQL databases. Set QUMA_TEST_DRIVERS and the database hosts as for composer test:all to include MySQL and PostgreSQL. Reports are written to .infection/.

License

This project is licensed under the MIT license.

celema / quma

Package info

Security

Statistics