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 celemas/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 Celemas\Quma\Connection;
use Celemas\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
• 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:

• Getting started
• Query files
• Parameters and results
• Templates
• Migrations overview
• CLI
• Testing

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.

License

This project is licensed under the MIT license.