README

Important note! This documentation was generated by an AI tool based on the codebase. Please treat the descriptions here with caution! Any translations of the documentation are also AI-generated, unless community input was involved.

A self-contained PHP data provider that turns a directory of NDJSON files into a small relational-style database. No external services, no daemons — just PHP talking to plain text files.

Designed for compact, low-traffic workloads where a real RDBMS would be overkill: configuration stores, internal tools, embedded use cases, prototypes.

Experimental note: this provider was built end-to-end via Claude Code under human guidance, as part of an experiment to develop a working software module purely through guided AI.

Fun note: this is a just-for-fun project with no ambition to be anything serious — after all, nobody in their right mind builds a database on JSON files 🙂

Features

Schema-driven NDJSON storage with per-table subdirectories
Auto-incrementing integer primary key (id) — invariant, not optional
Lookup and ordering indexes (including a mandatory PK index)
Schema evolution — add / drop / reorder / rename columns, rename and drop tables (migrateColumns, reorderColumns, renameColumn, renameTable, dropTable)
Query builder with WHERE, LIKE, BETWEEN, IN, ORDER BY, pagination, distinct
Foreign keys with cascade / setNull / restrict / noAction
Pluggable cache layer (APCu / Memcached / Redis / in-memory / your own)
Built-in integrity validator and repairer
Built-in backup / restore as .tar.gz archives, no shell required
A typed exception hierarchy: nine domain classes over a single vocabulary of situations, matched on rather than string-compared
Localized error messages (English / Russian, extensible to any locale), with every exception logged through PSR-3 when a logger is attached

Documentation

Need the documentation in your language, or want to help the community use this tool with docs in your own language? You are welcome to make a manual or automatic translation and propose it for inclusion via a pull request to this repository.

Requirements

PHP 8.4+
Bundled PHP extensions: ext-json, ext-phar, ext-zlib
One Composer runtime dependency: psr/log (^3) — the optional logger interface
Optional extensions: ext-apcu, ext-memcached, ext-redis (cache adapters), ext-intl (ComparisonModeEnum::Locale)

Quick taste

Map a table to a typed, immutable DTO and let the provider hydrate rows into objects:

use AV\JsonProvider\JsonDataProvider;
use AV\JsonProvider\Mapping\Attribute\JsonProviderRecord;
use AV\JsonProvider\Schema\TableSchema;

#[JsonProviderRecord('products')]
final class Product
{
    public function __construct(
        public int $id,
        public string $name,
        public float $price,
    ) {}
}

$db = JsonDataProvider::createDatabase('/path/to/db');

$db->createTable(TableSchema::create(
    name: 'products',
    columns: ['name' => 'string', 'price' => 'float'],
));
$db->registerDto(Product::class);

// id: 0 is a placeholder — the provider assigns the real id and returns it
$id = $db->table('products')
    ->insert(new Product(id: 0, name: 'Widget', price: 9.99));

$product = $db->table('products')->where('id', '=', $id)->selectOne();
// $product is a Product: typed fields, the real id, and (where declared)
// date/time columns as DateTimeImmutable and enum columns as enum cases

DTOs are the recommended surface — each value is validated against the schema on write, and reads come back as typed objects. When you would rather pass and receive plain arrays (no class, ad-hoc shapes), every method has a *ByArray twin — insertByArray, selectOneByArray, selectAllByArray, … See DTO mapping for the full contract.

License

MIT — see LICENSE.

alekvolsk / json-provider

Package info

Security

Statistics