PHPackages                             mameyugo/jsonq - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. mameyugo/jsonq

ActiveLibrary[Database & ORM](/categories/database)

mameyugo/jsonq
==============

High-performance JSON file storage engine for PHP, powered by Rust

v0.5.0(2mo ago)4257PHP-3.01RustPHP >=8.1CI passing

Since Feb 11Pushed 2mo agoCompare

[ Source](https://github.com/mameyugo/JsonQ)[ Packagist](https://packagist.org/packages/mameyugo/jsonq)[ Docs](https://github.com/mameyugo/JsonQ)[ GitHub Sponsors](https://github.com/sponsors/mameyugo)[ RSS](/packages/mameyugo-jsonq/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (5)Dependencies (2)Versions (15)Used By (0)

🚀 JsonQ
=======

[](#-jsonq)

**High-Performance JSON Storage Engine for PHP**

[![PHP Version](https://camo.githubusercontent.com/bf5636cbc371789cbd19fba904014740aca026d6f5d725b435fa0d3b224a1cf9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e31253230253743253230382e32253230253743253230382e33253230253743253230382e342d3737374242343f6c6f676f3d706870)](https://php.net)[![Rust](https://camo.githubusercontent.com/5fc8cb2244162f03a2c3cdcf79ce3ec0b10f993a9355399638b65902d75a268c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f527573742d312e37352532422d6f72616e67653f6c6f676f3d72757374)](https://rust-lang.org)[![License](https://camo.githubusercontent.com/5a2f6316aac55fd3a18669b5090a100b0c38d7995001b3b9b09d0526708165ce/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d504850253230332e30312d626c7565)](LICENSE)[![Performance](https://camo.githubusercontent.com/a20f9fbfa49abb9557111bdd3bedbfe3dbad64aad4210080e51fe519319fc1e4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f506572666f726d616e63652d322d2d3130782532306661737465722d627269676874677265656e)](docs/BENCHMARKS.md)

*MongoDB-style queries | JSON Schema validation | ACID transactions | 10x performance*

[Features](#-features) • [Quick Start](#-quick-start) • [Documentation](#-documentation) • [Benchmarks](#-performance) • [Contributing](#-contributing)

Version: **0.5.0**

---

📊 What is JsonQ?
----------------

[](#-what-is-jsonq)

JsonQ is a **blazing-fast PHP extension** written in Rust that provides a file-based JSON storage engine with MongoDB-style queries, schema validation, indexing, and transactions.

### Why JsonQ?

[](#why-jsonq)

- 🚀 **2-10x faster** than pure PHP JSON handling
- 💾 **File-based** - No server required, zero configuration
- 🔍 **MongoDB-style queries** - Familiar syntax with 17+ operators
- ✅ **Schema validation** - JSON Schema subset support
- 🔒 **ACID transactions** - Atomic operations with rollback
- 📊 **Indexing** - Hash-based O(1) lookups
- 🛡️ **Thread-safe** - OS-level file locking with fs2
- ⚡ **SIMD-accelerated** - Fast parsing with simd-json

---

✨ Features
----------

[](#-features)

### Core Storage

[](#core-storage)

- ✅ **CRUD Operations** with dot-notation path access
- ✅ **Atomic Writes** (tmp + fsync + rename) for crash safety
- ✅ **Memory-mapped I/O** for zero-copy reads
- ✅ **Arc-based Caching** with mtime invalidation
- ✅ **Compression Support** (Gzip, Zstd) - *v0.3.2*
- ✅ **Native Streaming** (v0.4.0) - Iterate gigabytes of data with low memory
- ✅ **Stream Filtering** - Apply MongoDB-style queries while streaming

### Query Engine

[](#query-engine)

- ✅ **MongoDB-style Matching**: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`
- ✅ **String Operators**: `$contains`, `$startsWith`, `$endsWith`, `$regex`
- ✅ **Logical Operators**: `$and`, `$or`, `$not`, `$nor`
- ✅ **Array Operators**: `$size`, `$all`, `$elemMatch`
- ✅ **Type Checking**: `$exists`, `$type`
- ✅ **Field Projection**: `select()` for whitelisting fields - *v0.3.2*
- ✅ **Query Optimizer**: Intelligent index selection - *v0.3.2*

### Fluent Query Builder

[](#fluent-query-builder)

- ✅ **Chainable Methods**: `where()`, `orWhere()`, `orderBy()`, `limit()`, `skip()`
- ✅ **Filtering**: Comparison, string, array operators
- ✅ **Sorting**: Ascending/descending on any field
- ✅ **Pagination**: `skip` + `limit` support

### Aggregation & Analysis

[](#aggregation--analysis)

- ✅ **Functions**: `sum()`, `avg()`, `min()`, `max()`, `count()`
- ✅ **Grouping**: `groupBy()` with field-based grouping
- ✅ **Field Extraction**: `pluck()` for column extraction

### Validation & Schema

[](#validation--schema)

- ✅ **JSON Schema Validation** (subset)
- ✅ **Type Constraints**: string, number, boolean, array, object
- ✅ **String Formats**: email, URL, IPv4, date, UUID
- ✅ **Number Constraints**: min, max, multipleOf
- ✅ **Array Constraints**: minItems, maxItems, uniqueItems
- ✅ **Required Fields** and enum validation
- ✅ **Conditional Logic**: if/then/else, oneOf, anyOf

### Indexing

[](#indexing)

- ✅ **Single Field Indexes**: O(1) equality lookups
- ✅ **Compound Indexes**: Multi-field indexing
- ✅ **Hash-based**: MD5 hashing for fast lookups
- ✅ **Auto-optimization**: Automatic use in `find()` queries

### Transactions

[](#transactions)

- ✅ **ACID Guarantees**: Atomic, Consistent, Isolated, Durable
- ✅ **Begin/Commit/Rollback**: Full transaction support
- ✅ **Isolation**: Transaction-local changes until commit

### Advanced Features *(v0.3.0)*

[](#advanced-features-v030)

- ✅ **Safe Regex** - ReDoS protection with backtracking limits
- ✅ **Metrics API** - Real-time observability (reads, writes, cache stats, latency)
- ✅ **Compression** - Transparent Gzip/Zstd support
- ✅ **Query Optimizer** - Intelligent index selection for complex queries

### Collection Methods *(v0.3.2)*

[](#collection-methods-v032)

- ✅ **`select(fields)`** - Project specific fields (whitelist)
- ✅ **`except(fields)`** - Exclude specific fields (blacklist)
- ✅ **`column(field)`** - Extract values from single column
- ✅ **`chunk(size)`** - Split results into groups
- ✅ **`implode(field, separator)`** - Join column values into string
- ✅ **`keys(path)`** - Get object keys
- ✅ **`values(path)`** - Get object values
- ✅ **`toJson(pretty)`** - Serialize results to JSON string

### Object Hydration *(NEW - v0.5.0)*

[](#object-hydration-new---v050)

- ✅ **Automatic Mapping** - Map JSON arrays directly into typed PHP 8.1+ objects
- ✅ **Typed Arrays** - Support for hydrating `array` via `#[Type]` attribute
- ✅ **HydratableStore** - Native extension wrapper with `findOneAs`, `findInAs`, `streamAs`
- ✅ **Type Coercion** - Configurable `STRICT` and `LENIENT` coercion modes
- ✅ **Round-trip Dehydration** - Convert PHP objects back into JSON natively
- 📖 [Learn more about Object Hydration](docs/HYDRATOR.md)

> **Legend**: ✅ Confirmed | ⏳ Pending verification

---

🚀 Quick Start
-------------

[](#-quick-start)

### Installation

[](#installation)

#### Via APT (Debian/Ubuntu)

[](#via-apt-debianubuntu)

```
# Add repository
curl -fsSL https://mameyugo.github.io/JsonQ/jsonq-archive-keyring.gpg | sudo gpg --dearmor -o /usr/share/keyrings/jsonq-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/jsonq-archive-keyring.gpg] https://mameyugo.github.io/JsonQ stable main" | sudo tee /etc/apt/sources.list.d/jsonq.list

# Install
sudo apt update
sudo apt install php8.3-jsonq

# Enable extension
php -m | grep jsonq
```

#### Via Curl (Quick Install)

[](#via-curl-quick-install)

```
curl -fsSL https://raw.githubusercontent.com/mameyugo/JsonQ/main/scripts/install.sh | sudo bash
```

#### Build from Source

[](#build-from-source)

```
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/mameyugo/JsonQ.git
cd JsonQ
cargo build --release

# Install
sudo cp target/release/libjsonq.so $(php-config --extension-dir)/jsonq.so
echo "extension=jsonq.so" | sudo tee /etc/php/8.3/mods-available/jsonq.ini
sudo phpenmod jsonq
```

### Hello World

[](#hello-world)

```