Download the PHP package bonsaicms/settings without Composer

bonsaicms/settings

A settings manager for Laravel that can persist any PHP value — not just strings and numbers, but arrays, objects and Eloquent models.

Other settings packages (e.g. anlutro/laravel-settings, akaunting/setting) store JSON-encodable scalars. This one serializes the value with PHP's serialize(), so whatever you put in is what you get out.

At a glance

Contents

• Installation
• How it works — read this before using the package
• API reference
• Storing Eloquent models
• Storing your own objects
• The settings() helper
• Middleware
• Artisan commands
• Configuration
• Architecture
• Gotchas
• Testing

Installation

The service provider and the Settings facade are auto-discovered. Publish the migration, then run it:

The migration is copied into your database/migrations with a fresh timestamp, so it belongs to your application — rename the table, change the column types or add an index before you run it. The package does not register it for you, so nothing is created behind your back. If you would rather not run every other pending migration in the application, point migrate at the published file (the publish command prints its full name, which starts with the timestamp it was stamped with):

Optionally publish the config file to config/settings.php:

Use --tag=settings to publish both at once.

That is enough to start using the package. The two middleware below are optional but recommended for web applications.

How it works

The write-behind cache

SettingsManager is registered as a singleton and holds every setting you touch in an in-memory Collection, deserialized. Reads fill that cache; writes only change it.

Call save() to flush:

Or register the SaveSettings middleware, which calls save() for you at the end of every request — but only when something actually changed (isDirty()).

Two flags drive the whole thing:

• isDirty() — becomes true on any set(), false again after save() or refresh().
• all() marks everything as loaded — once you have called all() (directly or through the LoadSettings middleware), the manager knows the full key set, so every later get() / has() is answered from memory with zero queries. A cache miss then means the key genuinely does not exist.

save() writes back the entire cache, not just the keys you changed.

null means "absent"

null is the sentinel for a missing setting throughout the package. There is no way to store a null value:

has($key) is literally get($key) !== null. Values like false, 0 and '' are stored and reported normally — only null is special.

Serialization

A value is stored as base64_encode(serialize($value)) — in a text column, a Redis hash field or a JSON key, depending on the driver — and read back with unserialize(base64_decode(...)).

Objects implementing BonsaiCms\Settings\Contracts\SerializationWrappable get special treatment: instead of serializing the object graph, the package stores the class name plus a small primitive payload you define, and rebuilds the object on read. See Storing your own objects.

Security note. Reading a setting runs unserialize() on whatever the driver hands back. Treat the settings store as trusted storage — the table, the Redis hash or the JSON file — and never let untrusted input write raw entries into it.

API reference

Every method is available on the Settings facade, on settings(), and on the SettingsManager contract.

Examples

Storing Eloquent models

Add the SerializableModelTrait to the model and declare the SerializationWrappable interface:

Then:

Model attributes are never serialized. The trait stores only the model class and its primary key, and calls MyModel::find($key) when the setting is read. Consequences:

• You always read back the current state of the row, not a snapshot from when it was saved.
• If the model is deleted from the database, Settings::get('model') returns null (and therefore has() returns false).
• The stored value stays tiny, whatever the size of the model.

If you need different behaviour, implement SerializationWrappable yourself instead of using the trait.

Storing your own objects

Any class can implement BonsaiCms\Settings\Contracts\SerializationWrappable:

• wrapBeforeSerialization($object) receives the object and returns a primitive payload (string, number, array …) that describes it. This payload is what gets serialized.
• unwrapAfterSerialization($class, $payload) receives the class name and that payload back, and returns the reconstructed object.

Objects that do not implement the interface are still supported — they just go through plain serialize(), which stores the whole object graph.

The settings() helper

settings() is a thin wrapper around the same singleton. It overloads on the shape of its arguments:

The get/set distinction for a single array argument is decided by its keys: sequential integer keys (0, 1, 2, …) mean get these keys, anything else means set these pairs.

The helper is registered through composer's files autoload, so it exists before any service provider boots. It still resolves the manager out of the container at call time, so calling it before the provider has registered fails on the binding, not on the function.

Middleware

Both middleware are optional. Register them in bootstrap/app.php:

• LoadSettings calls all() before the request is handled. One query up front, and every get() / has() during the request is then query-free.
• SaveSettings calls save() after the response is generated, but only if isDirty() — so read-only requests cost no writes.

Artisan commands

Calls Settings::deleteAll() on the default driver.

Empties one named driver instead, leaving the others alone.

Configuration

config/settings.php (publish it with --tag=settings-config):

Drivers

Storage works the way Laravel's cache stores do: default names one of the drivers, and each driver has a driver type plus its own settings.

Switching backend is one environment variable:

The names are yours, and two drivers may share a type. That is how you keep two sets of settings apart:

php artisan settings:delete-all --driver=tenant_two empties one driver without touching the others.

To add a driver of your own, implement Contracts\SettingsRepository with an array $config constructor and register its type:

The database table

Only the database driver needs a table. migrations.driver names the driver the published migration belongs to, so the migration follows that driver's connection and table:

Schema: key — varchar(255), primary key; value — text, not null; plus created_at / updated_at.

Swapping implementations

Every seam in the package is an interface bound from this array at register() time, so replacing any piece is a one-line config change. SettingsRepository is not in the list: it is bound to whichever driver default names.

Exceptions

By default (in production, with APP_DEBUG=false) a serialization failure is swallowed and the value becomes null. Turn these on to get a SerializeException / DeserializeException instead.

Architecture

Five contracts in src/BonsaiCms/Settings/Contracts/ are the extension points. Nothing is instantiated directly across a layer boundary — everything is resolved from the container.

SerializationWrappable is a sixth, user-facing interface — it is implemented by your classes, not by the package's internals.

Gotchas

Behaviours that are easy to get wrong — worth reading whether you are writing this code by hand or generating it:

1. set() does not write to the database. Only save() (or the SaveSettings middleware) does. Code that sets a value in an Artisan command or a queued job and never calls save() silently loses it.
2. deleteAll() is the exception — it hits the repository immediately and does not wait for save().
3. You cannot store null. Setting a key to null deletes it; reading a missing key gives null. Use a sentinel of your own if you need to distinguish "absent" from "explicitly empty".
4. refresh() throws away unsaved changes. It resets the cache and clears the dirty flag.
5. save() writes the whole cache, so after all() + save() every row is rewritten (and its updated_at bumped), not just the ones you changed.
6. get(array $keys) never omits keys. Missing ones come back as null, so the result count always matches the request, and the order matches too.
7. Serialization errors are silent in production. With APP_DEBUG=false a failed serialize/deserialize yields null rather than an exception — see Exceptions.
8. The stored format is PHP-specific. serialize() output is not readable by other languages, and changing the serializer breaks settings already stored in the wild.
9. The manager is a singleton, so its cache is shared for the whole request/process lifetime — including long-running workers (Octane, queue workers), where you may want refresh() between jobs.

Testing

The suite runs on Pest with orchestra/testbench simulating the host application, against an in-memory SQLite database. tests/Unit tests the manager against mocked collaborators; tests/Feature boots the service provider and exercises real persistence — including running the whole SettingsRepository contract against every driver.

Nothing in tests/Feature knows which driver it is running against, so the same suite can be pointed at any of them:

The Redis tests skip when there is no Redis to talk to, so composer test works on a machine without one. Point REDIS_HOST / REDIS_PORT at a server to run them, and REDIS_CLIENT at predis or phpredis to pick the client. Likewise DB_DRIVER (with DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD) swaps SQLite for a real pgsql, mariadb or mysql server.

CI runs composer test on every push in three sets of jobs:

• versions — every supported PHP (8.3, 8.4) × Laravel (12, 13), on SQLite.
• drivers — the whole suite once per driver: database, array, file and redis, the last on both Redis clients.
• databases — the database driver against real PostgreSQL, MariaDB and MySQL, since the upsert SQL is not the same on every engine.

SETTINGS_REQUIRE_REDIS=1 is set throughout, so a missing Redis fails the build instead of quietly skipping.

Related packages

Need to read and write settings over HTTP? See bonsaicms/settings-api.

License

MIT.