Laravel Kvstore Laravel Package

Getting Started

Start with the KvStore facade and the package’s key/value storage contract. The first useful flow is a simple write/read round trip:

KvStore::set('site.name', 'Acme');
KvStore::get('site.name');

For structured data, choose the cast at the write site. In v2.3.0 this is no longer optional for arrays, plain objects, and enums:

KvStore::set('features', ['beta' => true], 'array');
KvStore::get('features'); // array

If you are coming from 2.2, audit any calls that stored arrays or objects without a serialising cast before relying on reads.

Implementation Patterns

Use casts deliberately based on what the value column accepts:

• Strings, numbers, booleans, null, DateTimeInterface, and objects with __toString can be written without a cast.
• A Collection also works without a cast because it renders as its own JSON string, but make that choice intentionally.
• Arrays, plain objects, and enums need a cast that serialises the value: array, json, object, or collection.
• A scalar cast such as integer, string, or boolean does not serialise structured data. It is not a workaround for array writes.

Typical patterns:

// Plain values: no cast needed
KvStore::set('maintenance.enabled', true);
KvStore::set('released_at', now());

// Structured values: serialising cast
KvStore::set('features', ['beta' => true], 'array');
KvStore::set('payload', (object) ['id' => 1], 'json');

// Explicit serialisation if you want to own the format
KvStore::set('features', json_encode(['beta' => true]));

For application code, wrap writes where values may be dynamic:

$value = $request->input('settings');

KvStore::set(
    'settings',
    is_array($value) ? $value : json_decode($value, true),
    'array'
);

When reading, keep the cast contract consistent. If you write with 'array', read expecting an array. If you deliberately store raw JSON with no cast, read it as a string and decode it yourself.

Gotchas and Tips

• In v2.3.0, set() refuses values that cannot be written to the text column without a serialising cast. It throws InvalidArgumentException and writes nothing.

• The exception names the type it received and the cast that would fix it. Catch it at boundaries where user input or dynamic configuration is involved, and translate it into a validation error or domain exception.

• The same failure applies when a scalar cast is supplied for structured data:

  KvStore::set('features', ['beta' => true], 'integer'); // throws
  

• Before v2.3.0, an update could silently store an array as a raw JSON string. That value was indistinguishable from JSON stored intentionally. After upgrading, calls relying on that behaviour fail at write time instead of degrading silently.

• Audit upgrade paths for calls that stored arrays or plain objects without a cast, or with scalar casts. Add array, json, object, or collection, or serialise explicitly with json_encode().

• Do not assume “no cast” means “database will handle it.” On insert this previously caused Array to string conversion; on update it could produce a raw JSON string. v2.3.0 closes both paths.

• Items that remain valid without a cast: strings, numbers, booleans, null, DateTimeInterface, objects with __toString, and Collection instances.

• Enums require a cast. Plain objects without __toString require a cast or explicit serialisation.

• For custom casts, ensure assignment produces a string by the time the value reaches the text column. A cast that only scalarises the value is not sufficient for arrays or objects.

• Debugging tip: log the key and value type before calling set() in dynamic write paths. The exception message identifies the problematic type, but the key is usually what tells you which feature or configuration path needs fixing.