README

Waffle Data Component

Release: 0.1.0-beta3  |  CHANGELOG.md

The data & persistence layer for the Waffle Framework (RFC-022). Built for FrankenPHP resident-worker mode: a warm connection pool, a backend-agnostic query AST, parameterized SQL / Firestore compilers, a property-hook hydrator, and a stateless SQL migration runner. No stateful ORM, no identity map, no change tracking — a row becomes an immutable value object and nothing more.

📦 Installation

composer require waffle-commons/data

Requires PHP 8.5+ and ext-pdo. Depends only on waffle-commons/contracts (plus PSR + PHP core).

🧱 Surface

🚀 Quick start

Connection pool

use Waffle\Commons\Data\Connection\PDOConnectionPool;

$pool = new PDOConnectionPool(
    factory: static fn (): \PDO => new \PDO($dsn, $user, $pass, [
        \PDO::ATTR_ERRMODE => \PDO::ERRMODE_EXCEPTION,
    ]),
    maxConnections: 8,        // hard ceiling on simultaneously borrowed handles
    pingQuery: 'SELECT 1',    // liveness probe before dispensing
);

$connection = $pool->acquire();   // a healthy PDO, reconnected transparently if the socket died
// ... use $connection ...
$pool->release($connection);      // return it to the idle set
$pool->reset();                   // end-of-request: roll back stragglers, clear statement cache

Build a query, compile it for a backend

use Waffle\Commons\Data\Query\Query;
use Waffle\Commons\Data\Query\Criteria;
use Waffle\Commons\Data\Query\Direction;
use Waffle\Commons\Data\Compiler\SQLCompiler;
use Waffle\Commons\Data\Compiler\SQLDialect;

$query = Query::select('id', 'email')
    ->from('users')
    ->where(Criteria::eq('status', 'active'), Criteria::in('role', ['admin', 'editor']))
    ->orderBy('email', Direction::Ascending)
    ->limit(20);

$compiled = new SQLCompiler(SQLDialect::MySQL)->compile($query);
$compiled->sql;        // 'SELECT `id`, `email` FROM `users` WHERE `status` = ? AND `role` IN (?, ?) ORDER BY `email` ASC LIMIT 20'
$compiled->parameters; // ['active', 'admin', 'editor']

The same Query compiles to a Firestore payload via FirestoreCompiler with a FirestoreScope (public vs per-user path isolation).

Hydrate an immutable DTO

use Waffle\Commons\Data\Hydrator\PropertyHookHydrator;

$hydrator = new PropertyHookHydrator(UserDto::class);
$user = $hydrator->hydrate(['id' => '42', 'email' => 'ada@example.com']); // UserDto
// A malformed value is rejected by UserDto's `set` hook as a ValidationExceptionInterface.

Run migrations (from the CLI)

MigrationRunner is wired into the console as bin/waffle db:migrate (see the console component). Programmatically:

use Waffle\Commons\Data\Migration\MigrationRunner;

$runner = new MigrationRunner(pool: $pool, config: $config);
$applied = $runner->run(static fn (string $version) => printf("applied %s\n", $version));
// $applied: list of versions applied this run ([] when already up to date)

🐘 PHP 8.5 features used

• final readonly class for every value object (CompiledQuery, CompiledFirestoreQuery, Comparison, Order, FirestoreScope).
• Property Hooks — DTOs validate inside their own set hooks; the hydrator never sees invalid state. (A hooked DTO is final class + public private(set), since hooked properties cannot be readonly.)
• Asymmetric visibility (public private(set)) on the immutable Query builder.
• First-class callable syntax ($this->method(...)) in the compilers; enum with methods (Operator::isSetOperator()); never-returning rejection helpers; typed class constants.

🧭 Architectural boundary (mago guard)

Production code under Waffle\Commons\Data may depend only on Waffle\Commons\Data\**, Waffle\Commons\Contracts\**, Psr\**, and @global + Psl\**. A forbidden use fails the build, not a reviewer — enforced by vendor/bin/mago guard (bundled into composer mago, zero baselines). Interfaces must be named *Interface, Exception\** classes must end in *Exception, and any Enum\** namespace may hold only enum declarations.

Contract-first, component-agnostic by construction: the data layer composes with the rest of the framework through waffle-commons/contracts, never directly through another component.

🧪 Testing

docker exec -w /waffle-commons/data waffle-dev composer tests

The full gate (composer mago && composer tests) runs format, lint, analyze, guard, and PHPUnit (≥95% line coverage) with zero baselines.

📄 License

MIT — see LICENSE.md.