flexible-labs/json-store

Laravel-friendly JSON store with dot notation, auto-save, file locking, and TTL support.

v1.2.3 2025-04-12 20:28 UTC

Requires (Dev)

• orchestra/testbench: ^10.2
• phpunit/phpunit: ^12.1

MIT

• Suleiman Shahbari

README

Table of Contents

• Introduction
• Key Features
• Installation
• Configuration
• Quick Start
• API Reference
• Key Features
• Installation
• Configuration
• Quick Start
• Detailed Usage
  • Creating a Store
  • Setting and Retrieving Data
  • Managing Arrays
  • Caching with TTL
  • Concurrency Handling
  • Additional API Methods
• Practical Examples
• Testing
• Advanced Tips
• Comparison with Other Tools
• License
• Author

Introduction

JsonStore is a Laravel-friendly package that simplifies JSON-based storage. It enables you to store, retrieve, and manage structured data with ease using dot-notation, automatic persistence, caching, and file-locking mechanisms.

Key Features

• Dot Notation: Intuitively access and modify deeply nested JSON keys.
• Automatic Saving: Changes are persisted without manual save() calls.
• Safe Concurrency: File-level locking prevents race conditions.
• TTL Caching: Built-in remember() helper for temporary data storage.
• Flexible Storage: Works with any disk, base path, or multi-tenancy setup.

Installation

composer require flexible-labs/json-store

Configuration

php artisan vendor:publish --provider="FlexibleLabs\JsonStore\JsonStoreServiceProvider"

return [
    'disk'      => env('JSONSTORE_DISK', 'local'),
    'base_path' => env('JSONSTORE_BASE', ''),
];

Quick Start

use FlexibleLabs\JsonStore\JsonStore;

Route::get('/quick-start', function () {
    $store = JsonStore::make('settings.json');
    $store->set('theme', 'dark');
    return $store->get();
});

API Reference

Method	Description
make(filename, default = [], disk = null, base = null)	Create a new JsonStore instance.
disk(disk)	Set the storage disk.
base(path)	Set the base path inside the disk.
load()	Load the JSON file (auto-called on access).
save()	Manually save changes to the JSON file.
set(key, value)	Set a value by key (dot notation supported).
get(key = null, default = null, asObject = false)	Get a value or all data.
getOrSet(key, default)	Get value or set it if missing.
has(key)	Check if a key exists.
forget(key)	Remove a key.
delete(key, default = null)	Delete and return a value.
deleteFrom(key, valueToRemove)	Remove an item from an array.
insert(keyOrValue, value = null)	Append to array or to root.
replace(array)	Replace all data.
update(array)	Merge updates into current data.
remember(key, ttl, callback)	Cache value with TTL.
withLock(callback, deleteLockAfter = true)	Safely run operations with a file lock.
exists()	Check if the file exists.

Detailed Usage

Creating a Store

$store = JsonStore::make('config.json', ['theme' => 'light']);
$store = JsonStore::make('config.json')->disk('public')->base('configs');

Setting and Retrieving Data

$store->set('app.name', 'LaravelApp');
$store->set('app.version', '11.0');
$appName = $store->get('app.name');
$full = $store->get();

Managing Arrays

// Append a user to an array
$store->insert('users', 'John Doe');

// Remove a specific value from an array
$store->deleteFrom('users', 'John Doe');

// Replace the entire store content (use with caution)
$store->replace([
    'theme' => 'blue',
    'notifications' => ['email' => true, 'sms' => false]
]);

// Recursively update part of the data without overriding the rest
$store->update([
    'notifications' => ['push' => true],
    'app' => ['name' => 'Json Manager']
]);

Caching with TTL

$cached = $store->remember('api.response', 3600, fn () => Http::get(...)->json());

Concurrency Handling

$store->withLock(function () use ($store) {
    $views = $store->get('views', 0);
    $store->set('views', $views + 1);
});

Additional API Methods

getOrSet()

$token = $store->getOrSet('auth.token', fn () => Str::uuid());

forget()

$store->forget('deprecated.key');

delete()

$value = $store->delete('temp.value');

has()

if ($store->has('env.debug')) {
    // Do something
}

exists()

if ($store->exists()) {
    // File exists in storage
}

all() via get()

$data = $store->get();

set() with array

$store->set([
    'key1' => 'value1',
    'nested.key' => 'value2'
]);

insert() directly to root

$store->insert('a new root item');

Practical Examples

Dynamic Routes

Route::get('/articles/{id}', function ($id) {
    $store = JsonStore::make("{$id}.json")->disk('public')->base('articles');
    return $store->exists() ? $store->get() : abort(404);
});

Nested JSON Manipulation

$store = JsonStore::make('colors.json');
$store->set('1.name', 'red');
$store->set('1.code', '#ff0000');
return $store->get();

Testing

composer install
composer test

Advanced Tips

• Integrate with Laravel Echo for real-time sync.
• Use environment-specific disk/base for separation.
• Schedule regular exports via Laravel scheduler.

Comparison with Other Tools

Feature	JsonStore	Laravel Settings	Laravel JSON Settings
Dot notation	✅	✅	✅
Auto persistence	✅	❌	❌
File locking	✅	❌	❌
TTL caching	✅	❌	❌
Flexible paths	✅	❌	✅
Native Laravel feel	✅	✅	✅

License

JsonStore is open-source software licensed under the MIT license.

Author

Maintained by Suleiman Shahbari.