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
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.

License

This project is licensed under the MIT license.

celemas / quma

Maintainers

Package info

Statistics

Security