Download the PHP package niktomo/kura without Composer

Japanese version: README-ja.md

[!WARNING] This package is currently under active development. APIs may change without notice before v1.0.0.

Kura

Kura (蔵 — storehouse) is a Laravel package that caches reference data in APCu and queries it with a Laravel QueryBuilder-compatible API.

Load data once from CSV or DB, store it in APCu, and query it with the same fluent API you already know — no database queries at runtime. Index-accelerated lookups keep response times sub-millisecond even with large datasets.

Kura provides a QueryBuilder-compatible API backed by APCu (in-process memory), serving reference data entirely without touching the database at query time. Index-based lookups deliver fast filtered queries; generator-based full scans keep per-request memory use low. The design assumes that the pks list and index data for each table fit within APCu's configured shared memory.

Why Kura?

• Familiar API — where, orderBy, paginate, find, count, sum — same as Laravel's QueryBuilder
• Sub-millisecond reads — APCu shared memory, no network round-trips (see benchmarks)
• Low memory footprint — Generator-based traversal; never loads entire datasets into PHP memory
• Smart indexes — Binary search indexes for range queries, composite index hashmaps for O(1) multi-column lookups, automatic chunk splitting for large datasets
• Self-Healing — Cache eviction? Kura automatically rebuilds from the data source — your app never sees stale or missing data
• Version management — Switch reference data versions seamlessly via DB or CSV
• Pluggable data sources — LoaderInterface lets you bring any backend: CSV, Eloquent, QueryBuilder, REST API, S3, etc. Built-in loaders included; swap or extend with 5 methods

Requirements

• PHP 8.2 / 8.3 / 8.4 (8.5+ expected to work)
• Laravel ^11.0 / ^12.0 / ^13.0
• APCu extension (pecl install apcu)

Laravel Octane is not yet supported. Persistent processes require per-request state reset (version resolver, override) that is not yet implemented. Octane support is planned for v1.0.

Installation

Quick Start

1. Configure

Edit config/kura.php — the key sections for getting started:

2. Prepare your data

Kura supports two data sources: CSV files and Database (Eloquent).

Option A: CSV files

Organize CSV files by table, with a shared versions.csv:

versions.csv — controls which version is active:

The version with activated_at <= now and the latest timestamp is used.

stations/table.yaml — column types, index declarations, and primary key:

Supported types: int, float, bool, string

• Composite indexes ([col1, col2]) enable O(1) multi-column equality lookups
• If no indexes are needed, omit the indexes key entirely

Tip: primary_key defaults to id — only specify it if your table uses a different column name.

stations/data.csv — the actual data, with a version column:

The CsvLoader loads rows where version IS NULL (always loaded, shared across all versions) or version <= currentVersion (past and current versions). Rows where version > currentVersion are skipped (future versions not yet active).

Option B: Database (Eloquent)

No data CSV needed — load directly from your database. Column definitions and index declarations are read from table.yaml in the table directory:

Or with the version-managed resolver (recommended for production):

Option C: Custom Loader

Any data source works — implement LoaderInterface with 5 methods:

See Implementing a Custom Loader for a full example.

3. Register tables

Option A: Auto-discovery (CSV only)

The easiest approach when using CSV files — Kura scans a directory and registers every subdirectory that contains data.csv automatically. No AppServiceProvider code needed.

That's it — stations and lines are registered automatically. To override the primary key for a specific table:

Note: Adding a new table directory requires restarting the PHP process (php artisan octane:restart for Octane, or reloading PHP-FPM). The directory scan runs once at boot. Updating data inside an existing table (data.csv) also requires running php artisan kura:rebuild — there is no automatic file-change detection. Self-Healing only triggers on APCu TTL expiry, not on data.csv modification.

Option B: Manual registration

In your AppServiceProvider (or a dedicated service provider):

4. Build the cache

5. Query

How it works

When you call kura:rebuild, Kura loads data from your source (CSV or DB), stores each record in APCu, and builds search indexes. Subsequent queries read directly from shared memory — no database involved.

APCu key structure

Self-Healing

If APCu evicts cached data, Kura detects the loss at query time and automatically rebuilds from the data source. Your application always receives complete, correct results.

With rebuild.strategy = 'queue', the rebuild runs asynchronously — the current request gets data from the Loader directly while the cache is rebuilt in the background. With rebuild.strategy = 'callback', you supply a custom callable (e.g. to dispatch to a Horizon priority queue). See Cache Architecture for details.

Supported Query Methods

Kura implements ~99 methods from Laravel's QueryBuilder. For the complete list, see Laravel Builder Coverage.

WHERE

where, orWhere, whereNot, whereIn, whereNotIn, whereBetween, whereNull, whereNotNull, whereLike, whereColumn, whereAll, whereAny, whereNone, whereExists, whereFilter, whereRowValuesIn, and more.

ORDER BY / LIMIT / PAGINATION

orderBy, orderByDesc, latest, oldest, inRandomOrder, limit, offset, paginate, simplePaginate

RETRIEVAL / AGGREGATES

get, first, find, sole, value, pluck, cursor, count, min, max, sum, avg, exists

Documentation

Design Constraints & Extension Points

Kura is intentionally narrow in scope. Two operations are central: QueryBuilder-compatible filtering and index-based lookups. Everything else is either pluggable via interface/closure or fixed by design.

What you can extend

Fixed by design

See Design Constraints for extension patterns, memory model details, and contribution rules.

Configuration

All options are in config/kura.php. Below is the complete reference.

Benchmarks

Environment

Dataset

Synthetic product records with the following schema and indexes:

Indexes declared: country, price, country|category (composite).

Results (p95 latency)

Index-accelerated queries (bold) are 3–5× faster than full scans at the same dataset size. At 100K records, indexed queries respond in under 18 ms; a non-indexed full scan takes ~39 ms.

orderBy on an indexed column uses a pre-sorted index walk — no PHP sort needed. orderBy on a non-indexed column falls back to a PHP-side sort that collects all matching records into memory first (O(N)). For large tables, declare an index on any column you frequently sort by.

Run php benchmarks/benchmark.php in the Docker environment to reproduce.

With JIT + igbinary (100K records, p95)

Enabling PHP JIT and the igbinary APCu serializer delivers an additional 15–40% improvement across all query types.

JIT accelerates closure evaluation in the WhereCompiler and PHP-side sort. igbinary reduces APCu deserialization overhead on every record fetch.

To enable, add the following to your php.ini:

ext-igbinary can be installed via pecl install igbinary.

Cache Warming

Pre-warm the APCu cache via HTTP after deployment (before traffic arrives).

Enable the warm endpoint

Generate a Bearer token

Endpoints

POST /kura/warm — rebuild cache for all registered tables

GET /kura/warm/status/{batchId} — check async rebuild progress

Testing without APCu

Use ArrayStore as a drop-in replacement for ApcuStore in tests and CI:

ArrayStore operates on plain PHP arrays — no APCu extension required.

License

MIT