ray/fake-query

1.x-dev 2026-03-02 15:34 UTC

Requires

• php: ^8.2
• ray/di: ^2.18
• ray/media-query: ^1.0

Requires (Dev)

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

MIT

• Akihito Koriyama

README

A companion to Ray.MediaQuery that replaces SQL execution with JSON fixture files — no database required. Designed for testing and frontend development.

Ray.MediaQuery   SQL files  → DB execution → Entity
Ray.FakeQuery    JSON files → hydration    → Entity (same interface)

Installation

composer require ray/fake-query 1.x-dev --dev

Usage

Define query interfaces with #[DbQuery] as usual:

interface TodoQueryInterface
{
    #[DbQuery('todo_item')]
    public function item(string $todoId): ?TodoEntity;

    #[DbQuery('todo_list')]
    /** @return array<TodoEntity> */
    public function list(string $filterStatus = 'all'): array;

    #[DbQuery('todo_add')]
    public function add(string $todoId, string $title): void;
}

Swap modules to switch between real SQL and fake JSON:

// Production
$this->install(new MediaQuerySqlModule($sqlDir, $interfaceDir));

// Test / Frontend development
$this->install(new FakeQueryModule($fakeDir, $interfaceDir));

Create JSON files matching the query ID in #[DbQuery]:

var/fake/todo_item.json — single entity (?Entity):

{
    "todo_id": "01HVXXXXXX0008",
    "todo_title": "Buy groceries"
}

var/fake/todo_list.jsonl — collection (array<Entity>), one object per line:

{"todo_id": "01HVXXXXXX0008", "todo_title": "Buy groceries"}
{"todo_id": "01HVXXXXXX0007", "todo_title": "Call dentist"}

void methods require no file — they succeed silently as no-ops.

JSON keys use snake_case; entity properties use camelCase. Conversion is automatic, matching Ray.MediaQuery behavior.