- How do I install bgaze/laravel-kvstore in a Laravel application?
- Install it with Composer using composer require bgaze/laravel-kvstore. The package registers a service provider and exposes a facade, and it ships publishable config and migration files that you push into your app with the standard vendor:publish command. After publishing, run php artisan migrate to create the key-value table, then start calling the facade from your code.
- Does laravel-kvstore support dot notation for nested keys?
- Yes. The store supports dot-notation keys, so you can organise settings hierarchically, for example app.locale or features.beta, without creating separate columns or tables. This makes it convenient for grouping application settings and preferences under a single namespace. Retrieval and writes both go through the same intuitive facade API.
- How does type casting work when storing arrays or objects?
- Values are stored in a single text column, and an optional third argument to set() controls how the value is serialized on write. The cast vocabulary deliberately mirrors Eloquent, with array, json, object, and collection available for serializing values. Note that this argument governs only the write path, so scalar casts do not coerce values the way Eloquent casts do, and a missing cast on an array or object will now throw instead of being written silently.
- Why does storing an array throw an exception after upgrading to 2.3.0?
- Version 2.3.0 adds a validation guard at the top of set() so that a non-serializing write to the text column fails closed rather than degrading silently. Previously such writes failed loudly on insert but could write raw JSON on update, producing values indistinguishable from intentionally stored JSON strings. Fix affected call sites by supplying a serializing cast such as array, json, object, or collection, or by encoding the value yourself. Be aware that a scalar cast like integer is not a fix and will still throw.
- Which Laravel and PHP versions are supported by this package?
- The authoritative supported matrix is declared in the package's composer.json and README, so check those before adding it to an existing project. Because the 2.3.0 change tightens behavior, it is worth running your application test suite against the new version on a branch before merging. That also lets you confirm the guard behaves correctly on whichever database driver you use in production.
- Do I need to run a database migration to use laravel-kvstore?
- Yes. The package ships a publishable migration that creates the table holding the key, the text value column, and supporting fields. Publish it with vendor:publish and run php artisan migrate as part of your normal deployment. Upgrading to 2.3.0 does not require any new migration or config change, since the release only adds a write-time validation guard.
- Is the key-value store cached, and how do I keep it fresh?
- The package is cached by design, so repeated reads of the same key do not hit the database every time. This suits app settings and preferences that are read frequently but written rarely. When you write through the package's own API, cache handling is taken care of; if you modify the underlying table directly, such as during a data fix or backfill, clear the relevant cache entries so stale values are not served.
- How is laravel-kvstore different from Laravel's config or cache?
- Laravel's config repository is file-based and loaded per request, while the cache is a general-purpose ephemeral store with no persistent schema or typing. laravel-kvstore sits between the two: values live in a database table so they persist and can be edited at runtime, with a cache layer in front and per-entry type casting for structured values. It is intended for application settings, user preferences, and small configuration data rather than bulk storage.
- What kinds of values can I store, and what happens with booleans or null?
- Pass-through types such as strings, numbers, booleans, null, DateTimeInterface instances, objects implementing __toString, and Laravel collections are handled without special casting. Arrays, plain objects, and enums need an explicit serializing cast, or you can json_encode them yourself before writing. Version 2.3.0 added regression coverage for these pass-through types to lock in that behavior.
- Is laravel-kvstore production ready, and what risks should I plan for?
- The package is a small, conventional Laravel integration with no new dependencies and no schema changes beyond its own single table, which keeps adoption risk low. The main thing to plan for is release hygiene: 2.3.0 ships a behavior change as a minor version, so a routine composer update can surface exceptions at call sites that previously wrote silently degraded rows. The guard prevents new bad writes but does not clean up existing ones, so audit your set() call sites and consider identifying legacy raw-JSON rows before deploying.