Back to docs

Laravel Argonaut

Simple JSON value store using dot syntax. Cached for performance.

Laravel Support

Laravel Laravel Argonaut
10, 9 2
9, 8 1

What?

An easy settings store persisted in JSON files on your configured disks.

Why?

when you need to store arbitrarily structured data which might occasionally be updated by users. Kind of like dynamic config. Things like theme settings or global app preferences. I regularly need this functionality and whichever way I've tried to cut it, Eloquent seems the wrong tool for the job.

Installation

composer require fsac/laravel-argonaut

Publish the configuration file

php artisan vendor:publish --provider='FullStackAppCo\Argonaut\ServiceProvider'

Usage

Add a store by providing a stores configuration in your config/argonaut.php file. You must provide the name of a disk configured in your config/filesystems.php and a path on that disk where Argonaut should persist the store. Stores should be keyed with a unique name which will be used to retrieve them.

[
    'stores' => [
        'theme' => [
            'path' => 'settings/theme.json',
            'disk' => 'local',
        ],
    ],
]

The Argonaut facade can be used to retrieve a store which has been configured in config/argonaut.php

use FullStackAppCo\Argonaut\Facades\Argonaut;

Argonaut::store('theme');

Manipulating values:

$store = Argonaut::store('theme');

// Add a value to the store
$store->put('color', '#bada55');

// Persist the store to disk
$store->save();

// Retrieve a value
$store->get('color');
// -> '#bada55'

// Add a nested value
$store->put('colors.primary', '#bada55');

$store->get('colors');
// -> ['primary' => '#bada55']

// Retrieve a nested value
$store->get('colors.primary');
// -> '#bada55'

// Methods may be chained for convenience
Argonaut::store('theme')->put('colors.primary', '#bada55')->save();

You must call the save method to persist added values to disk.

Advanced Usage

You may also create an on-demand Argonaut instance using the build method of the Argonaut facade and passing a file path and disk instance:

use Illuminate\Support\Facades\Storage;

// Using a disk from filesystems config
$store = Argonaut::build('on-demand.json', Storage::disk('local'));
$store->put('font.heading', 'Menlo')->save();

// Using an on-demand disk
$store = Argonaut::build('on-demand.json', Storage::build([
    'driver' => 'local',
    'root' => '/path/to/root',
]));
$store->put('musicians.rainbow', ['rod', 'jane', 'freddy'])->save();

Testing

During testing an array driver is set to prevent data being persisted to disk.