Download the PHP package mameyugo/jsonq without Composer

📊 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?

• 🚀 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

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

• ✅ 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

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

Aggregation & Analysis

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

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

• ✅ 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

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

Advanced Features (v0.3.0)

• ✅ 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)

• ✅ 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)

• ✅ Automatic Mapping - Map JSON arrays directly into typed PHP 8.1+ objects
• ✅ Typed Arrays - Support for hydrating array<ClassName> 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

Legend: ✅ Confirmed | ⏳ Pending verification

🚀 Quick Start

Installation

Via APT (Debian/Ubuntu)

Via Curl (Quick Install)

Build from Source

Hello World

📚 API Reference

Basic Operations

CRUD

Array Operations

MongoDB-style Queries

Comparison Operators

Array Operators

String Operators

Logical Operators

Fluent Query Builder

Available Operators:

• Comparison: =, !=, >, >=, <, <=
• Array: in, not in
• String: contains, startsWith, endsWith
• Range: between (expects array [min, max])

Aggregation

Collection Methods (NEW)

Native Streaming (NEW - v0.4.0)

Process large JSON structures without loading everything into memory.

Schema Validation

Supported Constraints:

• Types: string, number, integer, boolean, array, object, null
• String: minLength, maxLength, pattern, format (email, url, ipv4, date, uuid)
• Number: minimum, maximum, multipleOf
• Array: minItems, maxItems, uniqueItems, items
• Object: required, properties, additionalProperties
• Enum: Fixed set of allowed values
• Conditional: if/then/else, oneOf, anyOf

Indexing

Performance Impact:

• Indexed find() queries: ~10x faster
• Index memory overhead: ~2-5% of data size
• Write penalty: <5% slower (hash computation)

Transactions

Guarantees:

• Atomicity: All changes commit together or none
• Consistency: Schema validation enforced
• Isolation: Changes invisible until commit
• Durability: fsync ensures disk persistence

Advanced Features (v0.3.0)

Compression

Metrics & Observability

Tracked Metrics:

• Read/write counters
• Cache hit/miss ratio
• Average read latency
• Last operation timestamp

Backup & Restore

Global Configuration

🏎️ Performance

Benchmarks (vs Pure PHP)

Benchmark environment: PHP 8.3, 10K documents, Intel i7-12700K

Optimization Tips

1. Use Indexes: 10-100x speedup for equality lookups
2. Enable Compression: 50-75% disk space reduction
3. Batch Writes: Use transactions for multiple operations
4. Monitor Metrics: Track cache hit rate and optimize queries
5. Project Fields: Use select to return only needed data

🏗️ Architecture

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Development Setup

Project Structure

📄 License

JsonQ is licensed under The PHP License, version 3.01.

🙏 Acknowledgments

• simd-json - SIMD-accelerated JSON parsing
• ext-php-rs - Safe Rust-PHP FFI bindings
• serde - Serialization framework
• MongoDB - Query syntax inspiration
• The Rust and PHP communities

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

🗺️ Roadmap

v0.6.0 (Q3 2026)

• [ ] JOIN operations across collections
• [ ] Full-text search with stemming
• [ ] JSONPath full support & advanced query optimizer improvements
• [ ] Watch API for change streams

v1.0.0 (Q4 2026)

• [ ] Production-ready stable API
• [ ] >98% test coverage
• [ ] Comprehensive documentation
• [ ] Performance parity with MongoDB for complex aggregate queries
• [ ] Multi-stage aggregation pipelines
• [ ] GraphQL-like query DSL