Json Key Value Store Laravel Package

Getting Started

• Install with Composer and review the package README first, especially the store creation, configuration, and exception sections. In Laravel, the first files to inspect are the service provider/config (if publishable), the store factory/constructor, and the tests covering file locking and JSON persistence.
• Create a dedicated writable directory under storage/app for the store, for example storage/app/key-value, and keep it out of public/. Ensure the web/queue user can create and modify files there.
• First use case: small, persisted application state such as feature flags, UI preferences, import checkpoints, or lightweight settings that do not belong in the primary database. Do not use it as a replacement for relational data or high-write-volume storage.
• Basic flow to verify after install:

$store = Store::open(storage_path('app/key-value'));

$store->put('theme', ['mode' => 'dark']);
$store->delete('theme');

// Reopen to confirm v4.0.1 delete persistence
$reopened = Store::open(storage_path('app/key-value'));
$reopened->get('theme'); // null

• v4.0.1 is a patch release with no indicated breaking changes. Upgrade normally, run your test suite, and add an explicit regression test that deletes a key, reopens the store, and asserts the key remains absent.

Implementation Patterns

• Bind a store instance per path in a Laravel service provider or resolve it through a small repository/service class. Avoid scattering Store::open(...) calls throughout controllers and jobs.
• Wrap store access in an application-specific service so callers use typed methods such as getUserPreference(), setImportCheckpoint(), or clearFeatureFlag() rather than raw string keys.
• Use the store for JSON-serializable values only: arrays, scalars, and simple objects. Normalize domain objects to arrays before writing.
• For read-modify-write workflows, perform the read and write close together and use the package’s locking behavior where available. Keep critical sections short; do not hold locks while calling external APIs or dispatching slow work.
• In queued jobs and console commands, open the store inside the job/command rather than serializing a store object into the queue payload. Pass the store path via config instead.
• Use one store path per bounded context, for example storage/app/imports and storage/app/preferences, rather than one shared global file for unrelated data.
• In tests, use a temporary directory per test, create a fresh store instance, and assert persistence after reopening. Cover delete, invalid JSON input, missing directory, unwritable file, compression enabled/disabled, and lock contention where relevant.
• Treat the new exceptions as part of normal integration: catch package-specific file, directory, JSON, compression, and lock exceptions at the service boundary, log context such as path and key, and return a controlled application error.
• Keep CI current with GitHub Actions. The package tests PHP 7.1 through PHP 8.5, but your application should still run its own supported PHP matrix.

Gotchas and Tips

• The delete persistence fix matters if you previously deleted keys and saw them reappear after reopening a store. Upgrade and add a regression test; do not assume old store files are automatically cleaned beyond the documented behavior.
• Missing directories and file-open failures now surface as clear exceptions. Ensure the directory exists during deployment and has correct permissions for both PHP-FPM and queue workers.
• JSON encoding failures usually come from resources, circular references, or invalid UTF-8. Sanitize values before writing and log the key/path, not the full payload if it may contain sensitive data.
• Compression support can fail due to missing extensions or misconfiguration. Enable it deliberately, verify the runtime has the required extension, and test that existing store files remain readable after changing the setting.
• Lock failures indicate contention or stale lock files. Reduce write frequency, avoid nested store operations, set sensible lock timeouts if configurable, and ensure failed jobs do not leave locks behind.
• Do not store secrets, tokens, or personal data in a plain JSON file unless the file permissions and encryption strategy are explicitly handled. Prefer Laravel’s encrypted storage or database for sensitive values.
• Check how relative store paths are resolved in Laravel, especially after config:cache. Prefer absolute paths such as storage_path(...) and clear config caches after changing store configuration.
• Catch narrow package exceptions rather than \Throwable; otherwise you may hide application bugs behind generic storage fallbacks.
• If you extend the package, keep custom encoders/decoders and filesystem adapters covered by the same exception and locking expectations as the core store.
• Upgrade notes: no breaking changes are indicated for v4.0.1. The main behavioral change to validate is delete persistence after reopening a store; the main operational change is more explicit exception reporting.