ray/media-query

PHP interface-based SQL framework

1.1.0 2026-05-06 14:39 UTC

Requires

• php: ^8.2
• ext-mbstring: *
• ext-pdo: *
• ext-tokenizer: *
• aura/sql: ^5.0 || ^6.0
• koriym/csv-entities: ^1.0
• koriym/null-object: ^1.0.1
• pagerfanta/pagerfanta: ^3.5 || ^4.7
• phpdocumentor/reflection-docblock: ^6.0
• phpdocumentor/type-resolver: ^2.0
• ray/aop: ^2.19
• ray/aura-sql-module: ^1.17
• ray/di: ^2.19
• ray/input-query: ^1.0

Requires (Dev)

• bamarni/composer-bin-plugin: ^1.8
• phpunit/phpunit: ^11.5

Suggests

• koriym/csv-entities: Provides one-to-many entity relation
• ray/web-query: For Web API query support

MIT

• Akihito Koriyama

README

Ray.MediaQuery

Interface-Driven SQL for PHP

Ray.MediaQuery lets SQL be SQL and objects be objects.

Define a PHP interface, attach #[DbQuery], write a SQL file, and Ray.MediaQuery provides the implementation through Ray.Di + AOP. Return types and docblocks drive fetching, hydration, pagination, and post-query result objects.

use Ray\MediaQuery\Annotation\DbQuery;

interface UserQueryInterface
{
    #[DbQuery('user_item')]
    public function item(string $id): ?User;
}

final class User
{
    public function __construct(
        public readonly string $id,
        public readonly string $name,
    ) {}
}

-- sql/user_item.sql
SELECT id, name FROM users WHERE id = :id;

$userQuery = $injector->getInstance(UserQueryInterface::class);
$user = $userQuery->item('user-123');

Why Ray.MediaQuery?

• Zero implementation code — interfaces become working query objects.
• SQL-first — use joins, CTEs, window functions, vendor-specific SQL, and query plans directly.
• Typed PHP results — hydrate rows to entities, typed collections, or custom result objects.
• Rich domain objects — use factory: classes, including DI-aware factories, to create computed or service-backed objects, such as exposing age from a stored birth_date.
• Explicit boundaries — SQL files, PHP interfaces, and domain objects remain visible and testable.
• AI-friendly — no hidden query generation; the contract is readable by humans and tools.

Installation

composer require ray/media-query

Quick Start

use Ray\AuraSqlModule\AuraSqlModule;
use Ray\Di\AbstractModule;
use Ray\Di\Injector;
use Ray\MediaQuery\Annotation\DbQuery;
use Ray\MediaQuery\MediaQuerySqlModule;

final class AppModule extends AbstractModule
{
    protected function configure(): void
    {
        $this->install(new MediaQuerySqlModule(
            interfaceDir: __DIR__ . '/Query',
            sqlDir: __DIR__ . '/sql',
        ));
        $this->install(new AuraSqlModule('sqlite::memory:'));
    }
}

interface TodoQueryInterface
{
    #[DbQuery('todo_add')]
    public function add(string $id, string $title): void;

    /** @return array<Todo> */
    #[DbQuery('todo_list')]
    public function list(): array;
}

$injector = new Injector(new AppModule());
$todoQuery = $injector->getInstance(TodoQueryInterface::class);
$todoQuery->add('todo-1', 'Write SQL');
$todos = $todoQuery->list();

Result Types at a Glance

Declaration	Meaning
array	List of associative rows
?array + type: 'row'	Single associative row or null
/** @return array<User> */ array	Hydrated entity list
?User + type: 'row'	Single hydrated entity or null
void	Execute DML and ignore the result
AffectedRows	DML row count
InsertedRow	INSERT id and resolved bound values
Pages<User>	Lazy paginated hydrated rows
PostQueryInterface	Custom post-query result object

Documentation

Start from the Documentation Home. It is the single entry point for the manual, hands-on tutorial, BDR pattern, FAQ, ecosystem links, and AI-oriented reference.

Demo Application

See demo/ for a minimal runnable smoke test of the module wiring. The hands-on tutorial in the documentation site is the full feature walkthrough.

Philosophy

Ray.MediaQuery does not hide SQL to make objects comfortable, and it does not flatten objects to make SQL convenient. It lets both sides do what they are good at: SQL expresses data access precisely, while PHP expresses types, domain behavior, and dependency-injected object construction.