README

Saya bikin BangronDB karena di project-project saya (ERP, CRM, POS, HRIS) saya berulang kali butuh hal yang sama: database dokumen yang fleksibel, bisa di-deploy tanpa setup server, dan punya API yang enak dipakai. MongoDB-style API di atas SQLite adalah jawaban saya.

Library ini cocok untuk aplikasi yang di-deploy per-customer (appliance model), embedded di sistem existing, atau project SMB yang tidak butuh PostgreSQL/MySQL. Bukan untuk SaaS multi-tenant skala besar — gunakan PostgreSQL + RLS untuk itu.

Sorotan Fitur

• API mirip MongoDB untuk operasi dokumen
• Backend SQLite berbasis file atau in-memory
• Dual query strategy: SQL-first via json_extract, fallback ke PHP-side UtilArrayQuery untuk query kompleks
• Enkripsi dokumen dengan AES-256-GCM + key rotation (v1.2.0)
• Searchable fields (blind index SHA-256) untuk query pada data terenkripsi
• Hooks untuk lifecycle insert, update, dan remove
• Schema validation: type, enum/options, regex, min/max, unique constraint
• Aggregation pipeline: $match, $group, $sort, $limit, $skip, $project, $count, $unset
• Soft delete dengan restore dan force delete
• TTL (Time-To-Live) auto-expiration
• Cursor streaming via PHP Generator untuk efisiensi memori
• ID mode fleksibel: UUID, manual, prefix
• Populate relasi antar-collection dan antar-database
• EXPLAIN query plan dan optimization suggestions
• Health metrics, integrity check, dan change notification
• Konfigurasi collection yang persisten ke database
• Security auditor utilitas (opsional)

Arsitektur

Struktur Kode

src/
├── Client.php              # Entry point: mengelola banyak database
├── Database.php            # Satu file .bangron / :memory:
├── Collection.php          # Tabel dokumen (menggunakan traits)
├── Cursor.php              # Lazy query result iterator
├── QueryExecutor.php       # Eksekusi SQL via PDO prepared statements
├── UtilArrayQuery.php      # PHP-side query engine (fallback)
├── Config.php              # Global configuration
├── Enums/                  # Enum: HookEvent, IdMode
├── Exceptions/             # Typed exceptions
├── Security/               # SecurityAuditor (utilitas opsional)
└── Traits/                 # Fitur-fitur collection (horizontal reuse)
    ├── QueryBuilderTrait.php
    ├── EncryptionTrait.php
    ├── SchemaValidationTrait.php
    ├── HooksTrait.php
    ├── SearchableFieldsTrait.php
    ├── IdGeneratorTrait.php
    ├── SoftDeleteTrait.php
    ├── TtlTrait.php
    ├── ChangeTrackingTrait.php
    └── ConfigurationPersistenceTrait.php

Desain Trait-based

Collection menggunakan traits untuk horizontal code reuse — bukan inheritance. Setiap trait adalah unit tunggal yang fokus pada satu tanggung jawab:

Pendekatan ini menjaga Collection.php tetap ringan sebagai koordinator, sementara logika detail tersebar di file terpisah yang bisa di-maintain secara independen.

Dual Query Strategy

BangronDB menggunakan dua lapis query secara otomatis:

Query masuk → _canTranslateToJsonWhere()?
                ├─ YA → _buildJsonWhere() → SQL WHERE via json_extract/->>/->  (cepat)
                └─ TIDAK → fetch semua → UtilArrayQuery::match() di PHP        (fleksibel)

• SQL-first: Query sederhana (equality, comparison, $in, logical operators) diterjemahkan ke SQL WHERE json_extract(document, '$.field') dan dieksekusi langsung oleh SQLite engine. Ini memanfaatkan index dan meminimalkan data yang di-load ke PHP.
• PHP fallback: Query kompleks (regex, closure/$where, fuzzy search, dot notation nested) yang tidak bisa diterjemahkan ke SQL menggunakan UtilArrayQuery untuk filtering di level PHP.

Strategi ini otomatis — pengguna tidak perlu memilih secara manual.

Yang BUKAN Bagian Core

Beberapa fitur yang sering dikira built-in sebenarnya adalah pola aplikasi yang didemonstrasikan di examples/, bukan bagian dari library:

• RBAC/ACL → Contoh 22, 23, 24: pola menggunakan setCustomConfig() + hooks untuk enforce permission di application layer
• Change tracking audit log → Contoh di examples: pola menggunakan hooks untuk mencatat perubahan
• Authentication → Contoh 20: pola hashing password + hooks

BangronDB menyediakan primitif (hooks, schema, custom config) yang memungkinkan pola-pola ini dibangun di atasnya, tanpa memaksakan paradigma tertentu ke aplikasi pengguna.

Kebutuhan Sistem

• PHP 8.1+
• Ekstensi pdo_sqlite
• Ekstensi openssl
• Composer

Instalasi

composer require herdianrony/bangrondb

Quick Start

use BangronDB\Client;

$client = new Client(__DIR__ . '/data');
$client->createDB('app');
$client->createCollection('app', 'users');

$users = $client->selectCollection('app', 'users');

// Insert
$userId = $users->insert([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'role' => 'admin',
]);

// Find
$user = $users->findOne(['_id' => $userId]);

echo $user['name'] . PHP_EOL;

// Update
$users->update(['_id' => $userId], [
    '$set' => ['role' => 'superadmin'],
]);

// Delete
$users->remove(['_id' => $userId]);

Konsep Dasar

Client -> Database (.bangron / :memory:) -> Collection -> Document

• Client mengelola banyak database dalam satu path.
• Database mewakili satu file SQLite/BangronDB.
• Collection mewakili tabel dokumen.
• Document disimpan sebagai JSON.

Membuat Client dan Database

use BangronDB\Client;

// File-based storage
$client = new Client(__DIR__ . '/data');

// In-memory
$memoryClient = new Client(':memory:');

// Dengan opsi runtime
$secureClient = new Client(__DIR__ . '/data', [
    'encryption_key' => $_ENV['DB_ENCRYPTION_KEY'] ?? null,
    'query_logging' => false,
    'performance_monitoring' => false,
]);

// API eksplisit untuk lifecycle database
$client->createDB('app');
$client->dbExists('app'); // true

$db = $client->selectDB('app');
$db = $client->app; // magic getter, untuk database yang sudah ada

$client->createCollection('app', 'users');
$client->collectionExists('app', 'users'); // true
$client->listCollections('app');           // ['users', ...] (alias: listCollection)

$users = $client->selectCollection('app', 'users');
$users = $db->users; // magic getter, untuk collection yang sudah ada

$client->renameCollection('app', 'users', 'members');
$client->dropCollection('app', 'members');

// Atau dari object Database jika lebih nyaman
$db->createCollection('logs');
$db->collectionExists('logs'); // true

// Rename / hapus database
$client->renameDB('app', 'app_v2');
$client->dropDB('app_v2');

$client->close();

Mulai versi ini, selectDB() dan selectCollection() bersifat non-lazy: keduanya hanya memilih resource yang sudah ada.

Untuk membuat resource baru secara eksplisit, gunakan:

• createDB() untuk database
• createCollection() untuk collection

CRUD

Insert

$id = $users->insert([
    'name' => 'Alice',
    'email' => 'alice@example.com',
]);

$count = $users->insert([
    ['name' => 'Bob'],
    ['name' => 'Charlie'],
]);

InsertMany / UpdateMany / DeleteMany (API MongoDB-compatible)

// InsertMany: insert batch dengan hasil detail
$result = $users->insertMany([
    ['name' => 'Alice', 'email' => 'alice@example.com'],
    ['name' => 'Bob',   'email' => 'bob@example.com'],
]);
// ['inserted_count' => 2, 'inserted_ids' => ['...', '...']]

// UpdateMany: update semua dokumen yang cocok
$result = $users->updateMany(['status' => 'pending'], ['$set' => ['status' => 'active']]);
// ['matched_count' => 5, 'modified_count' => 5]

// DeleteMany
$result = $users->deleteMany(['status' => 'banned']);
// ['deleted_count' => 2]

Find

$all = $users->find()->toArray();
$one = $users->findOne(['name' => 'Alice']);

$activeAdults = $users->find([
    'status' => 'active',
    'age' => ['$gte' => 21],
])->toArray();

$projection = $users->find(
    ['status' => 'active'],
    ['name' => 1, 'email' => 1]
)->toArray();

$total = $users->count(['status' => 'active']);

Update

// Merge update (default)
$users->update(['name' => 'Alice'], ['city' => 'Jakarta']);

// Replace update
$users->update(['name' => 'Alice'], ['name' => 'Alice', 'city' => 'Bandung'], false);

// Operator-style update
$users->update(['name' => 'Alice'], [
    '$set' => ['role' => 'editor'],
    '$unset' => ['legacy_field' => ''],
]);

Save / Upsert

// Tanpa _id => insert baru
$newId = $users->save(['name' => 'Dina']);

// Dengan _id => update jika sudah ada, insert jika belum ada
$users->save([
    '_id' => 'USR-000001',
    'name' => 'Dina Updated',
]);

Delete

$deleted = $users->remove(['status' => 'inactive']);
$users->remove([]); // hapus semua dokumen

Pagination, Sorting, Projection

$results = $users->find(['status' => 'active'])
    ->sort(['age' => 1])
    ->skip(10)
    ->limit(5)
    ->toArray();

Query Operators

Comparison

$users->find(['age' => ['$gt' => 18]]);
$users->find(['age' => ['$gte' => 21]]);
$users->find(['age' => ['$lt' => 65]]);
$users->find(['age' => ['$lte' => 60]]);
$users->find(['age' => ['$ne' => 30]]);

Array / Membership

$users->find(['role' => ['$in' => ['admin', 'editor']]]);
$users->find(['role' => ['$nin' => ['guest', 'banned']]]);
$users->find(['tags' => ['$all' => ['php', 'sqlite']]]);
$users->find(['tags' => ['$size' => 3]]);

Existence dan Logical

$users->find(['email' => ['$exists' => true]]);

$users->find(['$or' => [
    ['age' => ['$lt' => 18]],
    ['age' => ['$gt' => 65]],
]]);

$users->find(['$and' => [
    ['status' => 'active'],
    ['age' => ['$gte' => 21]],
]]);

Regex, Closure, Fuzzy Search, Dot Notation

$users->find(['name' => ['$regex' => '^John']]);

$users->find(['age' => ['$where' => fn($doc) => $doc['age'] > 18]]);
$users->find(['name' => ['$func' => fn($val) => strlen($val) > 5]]);

$users->find([
    'description' => [
        '$fuzzy' => [
            '$search' => 'important',
            '$minScore' => 0.7,
        ],
    ],
]);

$users->find(['address.city' => 'Jakarta']);

'$where' dan '$func' hanya menerima Closure, bukan string function name.

Aggregation Pipeline

$results = $users->aggregate([
    ['$match'  => ['status' => 'active']],
    ['$group'  => ['_id' => '$role', 'total' => ['$sum' => 1], 'avg_age' => ['$avg' => '$age']]],
    ['$sort'   => ['total' => -1]],
    ['$limit'  => 10],
]);

Operator yang didukung:

Field reference menggunakan prefix $: '$fieldName' merujuk ke nilai field dokumen.

Cursor Streaming

Untuk dataset besar, gunakan stream() yang menghasilkan Generator — memori tetap konstan terlepas dari ukuran hasil:

foreach ($users->stream(['status' => 'active'], [
    'sort'  => ['created_at' => -1],
    'limit' => 10000,
]) as $doc) {
    processDocument($doc); // hanya satu dokumen di memori
}

Explain Query

Analisis bagaimana query dieksekusi — apakah menggunakan index, full scan, dan saran optimasi:

$explanation = $users->explain(['status' => 'active', 'age' => ['$gte' => 21]]);

echo $explanation['query_plan']['uses_index'] ? 'Uses index' : 'Full scan';
echo "Scanned: {$explanation['performance']['documents_scanned']} documents";
echo "Time: {$explanation['performance']['execution_time_ms']}ms";

foreach ($explanation['suggestions'] as $suggestion) {
    echo "Suggestion: {$suggestion}";
}

Enkripsi

Database-level encryption

use BangronDB\Database;

$db = new Database(__DIR__ . '/secure.bangron', [
    'encryption_key' => $_ENV['DB_ENCRYPTION_KEY'],
]);

Collection-level encryption

$users->setEncryptionKey($_ENV['DB_ENCRYPTION_KEY']);

$users->insert([
    'name' => 'Alice',
    'ssn' => '123-45-6789',
]);

Searchable fields untuk data terenkripsi

$users->setEncryptionKey($_ENV['DB_ENCRYPTION_KEY']);

// Format baru (direkomendasikan) — kontrol per-field
$users->setSearchableFields([
    'email' => ['hash' => true],     // HMAC-SHA256 blind index (aman)
    'username' => ['hash' => false], // Plain text (untuk field non-sensitif)
]);

// Format lama (masih didukung) — semua field mendapat perlakuan sama
$users->setSearchableFields(['email', 'phone'], true);

$users->saveConfiguration();

Catatan teknis: BangronDB menggunakan AES-256-GCM, key derivation berbasis PBKDF2 SHA-256, IV acak per enkripsi, dan payload Base64 di dokumen JSON. Key version (v1.2.0) memungkinkan key rotation tanpa re-encrypt manual.

Key Rotation

// Set key lama, lalu rotate ke key baru
$users->setEncryptionKey($oldKey, 'v1');
$rotated = $users->rotateEncryptionKey($newKey, 'v2'); // return jumlah dokumen

// Set key baru sebagai active
$users->setEncryptionKey($newKey, 'v2');

Lihat contoh 21 (21-key-rotation.php) untuk demo lengkap termasuk reencryptAll().

Schema Validation

$users->setSchema([
    'username' => ['required' => true, 'type' => 'string', 'min' => 3, 'max' => 50],
    'email'    => ['required' => true, 'type' => 'string', 'unique' => true, 'regex' => '/^[^\s@]+@[^\s@]+\.[^\s@]+$/'],
    'age'      => ['type' => 'int', 'min' => 13, 'max' => 120],
    'role'     => ['type' => 'string', 'enum' => ['admin', 'user', 'moderator']],
]);

$users->validate([
    'username' => 'john',
    'email' => 'john@example.com',
]);

Validasi enum menggunakan strict comparison. Misalnya, nilai 0, false, dan '0' dianggap berbeda.

Unique constraint

Tandai sebuah field dengan 'unique' => true agar BangronDB menolak dokumen baru (atau update) yang nilainya sudah ada di koleksi. Pengecekan dijalankan otomatis saat insert() / update() dan melempar ValidationException (UNIQUE_CONSTRAINT_VIOLATION). Nilai null tidak dikenai constraint, dan update pada dokumen yang sama (nilai tidak berubah) tidak dianggap duplikat.

$users->setSchema(['email' => ['type' => 'string', 'unique' => true]]);
$users->insert(['email' => 'a@example.com']);
$users->insert(['email' => 'a@example.com']); // throws ValidationException

Catatan untuk field terenkripsi: pengecekan unik memakai query equality, sehingga pada koleksi terenkripsi field tersebut harus juga dijadikan searchable (setSearchableFields([... => ['hash' => true]])) agar nilai dapat dicari lewat blind index. Tanpa itu, dokumen terenkripsi tidak bisa di-query per-nilai dan constraint tidak akan menemukan duplikat.

Lihat docs/schema-metadata-guide.md untuk panduan lengkap tentang properti metadata (label, ui, relation, dll.) yang tidak divalidasi otomatis.

TTL (Time-To-Live)

Dokumen bisa di-set untuk auto-expire setelah waktu tertentu:

// Aktifkan TTL pada field 'expires_at' dengan default 1 jam
$logs->enableTtl('expires_at', 3600);

// Tanpa default TTL (set manual per dokumen)
$logs->enableTtl('expires_at');

$logs->insert(['message' => 'temp log']); // otomatis dapat expires_at = now() + 3600

// Insert dengan expiry manual (override default)
$logs->insert(['message' => 'short', 'expires_at' => time() + 300]);

// Bersihkan dokumen yang sudah expired
$removed = $logs->cleanExpired();

// Statistik TTL
$stats = $logs->ttlStats();

cleanExpired() harus dipanggil manual (misalnya via cron). BangronDB tidak membersihkan otomatis.

Soft Deletes

$users->useSoftDeletes(true);

$users->remove(['username' => 'johndoe']);
$users->find()->withTrashed()->toArray();
$users->find()->onlyTrashed()->toArray();
$users->restore(['username' => 'johndoe']);
$users->forceDelete(['username' => 'johndoe']);

Hooks

$users->on('beforeInsert', function ($document) {
    $document['created_at'] = date('c');
    return $document;
});

$users->on('afterInsert', function ($document, $insertId) {
    error_log('Inserted: ' . $insertId);
});

$users->on('beforeUpdate', function ($criteria, $data) {
    $data['updated_at'] = date('c');
    return ['criteria' => $criteria, 'data' => $data];
});

$users->on('beforeRemove', function ($document) {
    if ($document['protected'] ?? false) {
        return false; // reject deletion
    }
});

Event yang tersedia:

• beforeInsert / afterInsert
• beforeUpdate / afterUpdate
• beforeRemove / afterRemove

Hook adalah primitif yang fleksibel. Bisa digunakan untuk ACL enforcement, audit logging, auto-timestamp, data transformation, dan lain-lain — semuanya di application layer, bukan di core library.

Relationships / Populate

$posts = $db->posts->find()
    ->populate('author_id', $db->users, ['as' => 'author'])
    ->toArray();

$post = $db->posts->populate($post, 'comment_ids', 'app.comments', '_id', 'comments');

Indexing

$users->createIndex('email');
$users->createIndex('address.city');
$users->createIndex('status', 'idx_status');

$db->dropIndex('idx_status');

Health & Monitoring

$health = $db->getHealthMetrics();
$report = $db->getHealthReport();
$perf   = $db->getPerformanceMetrics();
$index  = $db->getIndexMetrics();
$coll   = $db->getCollectionMetrics();

$db->checkIntegrity();
$db->vacuum();

Change Notification

$lastModified = $users->getLastModified();
// ['version' => 42, 'last_updated' => '2026-06-20T10:30:45+07:00']

$users->notifyChange();

Dynamic Configuration

Konfigurasi collection berikut bisa disimpan ke database:

• ID mode
• searchable fields
• schema
• soft deletes
• custom config

$users->setIdModePrefix('USR');
$users->setSearchableFields(['email'], true);
$users->setSchema([...]);
$users->useSoftDeletes(true);
$users->saveConfiguration();

Custom Config

Simpan metadata aplikasi per collection — persisten dan auto-load saat reconnect:

// Simpan ACL, settings, atau metadata lain
$users->setCustomConfig('acl', [
    'admin'  => ['create', 'read', 'update', 'delete'],
    'editor' => ['create', 'read', 'update'],
    'viewer' => ['read'],
]);
$users->setCustomConfig('max_login_attempts', 3);
$users->saveConfiguration();

// Baca kapan saja
$acl = $users->getCustomConfig('acl');
$all = $users->getAllCustomConfig();

Sensitive keys (encryption_key, password, secret, token, dll.) ditolak otomatis dan tidak bisa disimpan via setCustomConfig. Encryption key selalu supply dari .env, secret manager, atau runtime config.

Catatan: konfigurasi ID prefix yang dipersist kini dinormalisasi ke format prefix:USR. Konfigurasi lama yang masih menyimpan prefix mentah seperti USR tetap didukung saat dibaca ulang.

Transactions

BangronDB menggunakan PDO SQLite di bawahnya, jadi Anda bisa memakai transaksi langsung lewat koneksi PDO:

$db->connection->beginTransaction();

try {
    $db->users->insert(['name' => 'Alice']);
    $db->profiles->insert(['user' => 'Alice']);
    $db->connection->commit();
} catch (\Throwable $e) {
    $db->connection->rollBack();
    throw $e;
}

Keamanan

BangronDB menerapkan beberapa guardrail penting:

Lihat juga SECURITY_USAGE_GUIDE.md.

API Ringkas

Client

Database

Collection

Cursor

Konfigurasi Environment

Salin .env.example menjadi .env lalu isi sesuai kebutuhan:

DB_PATH=                         # Kosongkan untuk in-memory
ENCRYPTION_KEY=                  # Key kuat minimal 32 karakter
QUERY_LOGGING=false
PERFORMANCE_MONITORING=false

Contoh Lengkap

Lihat folder examples/ untuk contoh end-to-end:

Dokumentasi

Catatan Kompatibilitas

Jika Anda bermigrasi dari perilaku lama yang mengandalkan create implicit saat selectDB() / selectCollection(), lihat:

• BACKWARD_COMPATIBILITY_NOTES.md

Kontribusi

Lihat CONTRIBUTING.md.

Lisensi

BangronDB dilisensikan dengan MIT.