Valuestore Laravel Package

Getting Started

1. Install via Composer: composer require spatie/valuestore
2. Create a new store instance or use Laravel’s automatic facade binding:

   use Spatie\ValueStore\Facades\Valuestore;
   Valuestore::put('feature_flags', ['dark_mode' => true]);
   

3. Specify storage location (Laravel defaults to storage/app/valuestore.json—override via config if needed)
4. First real-world use: store a single app setting or cached transient state without DB overhead, e.g., Valuestore::put('last_deploy_hash', git rev-parse HEAD).

Start by checking the examples/ directory in the repo for minimal usage snippets. In Laravel, you’ll get Valuestore facade out-of-the-box after installation.

Implementation Patterns

• Config-like persistence: Store runtime-tweakable settings in config/app.php (e.g., Valuestore::put('maintenance_mode', true) instead of editing .env or DB)
• Feature flags: Use arrays for toggles:

  if (Valuestore::get('features.new_checkout', false)) { ... }
  

• One-off caches: Persist computed values across requests without cache drivers:

  Valuestore::remember('api_response_cache', 300, fn() => expensiveApiCall());
  

• CLI tools / scripts: Store ephemeral state between script runs (e.g., migration cursor, progress token)
• Testing: Use in feature tests to persist test-specific state across assertions:

  Valuestore::put('test_session_id', $id);
  $this->assertEquals($id, Valuestore::get('test_session_id'));
  

For Laravel, extend via Valuestore::extend('custom_key', $callback) to support dynamic default values with fallback logic.

Gotchas and Tips

• Atomic writes: Avoid concurrent writes under heavy load—use Laravel queues or locks for batch updates.
• No TTL by default: remember() only works for the current request lifecycle unless manually persisted. For persistent cache with expiration, layer with Laravel’s cache or manually encode timestamps.
• Performance caveat: Larger files (>1–2MB) or frequent writes may cause slowdowns; avoid using for high-frequency operations (e.g., request counters).
• Array modifications: Direct array changes (e.g., $data = Valuestore::get('foo'); $data['bar'] = 1;) won’t persist—always re-save: Valuestore::put('foo', $data)
• Testability: In tests, bind a custom Valuestore instance via Valuestore::fake() or Valuestore::spy() to avoid filesystem side effects
• Customization: Override default storage path via constructor: new Valuestore(\Storage::path('custom.json'))
• Debugging tip: Valuestore::all() reveals full contents—use in tinker or debug middleware to inspect stored data.