Weave Code
Fulcrum Settings Laravel Package
gaiatools/fulcrum-settings
Fulcrum Settings is a Laravel package for storing and managing application settings in the database, with a simple API, cached reads, and support for runtime configuration changes.
Fulcrum Settings is a Laravel package for managing application settings through a flexible, database-backed key/value store. It provides a simple API for reading, writing, and organizing configuration values at runtime, with sensible fallbacks when a setting is missing.
- Database-backed settings for runtime configuration
- Simple get/set API for reading and updating values
- Caching support to reduce database queries
- Default values and fallback resolution
- Organized settings for cleaner configuration management
Frequently asked questions about Fulcrum Settings
- How do I install gaiatools/fulcrum-settings in a Laravel application?
- Install it with Composer using a constraint of ^2.0.1, then let Laravel's package discovery register the service provider. You will typically publish the package config and run its migrations so the settings table exists. Add the package trait or implement its contract on any model that should own settings, such as a Team or Tenant model. Always install 2.0.1 or later rather than pinning 2.0.0.
- Which Laravel and PHP versions does fulcrum-settings support?
- The 2.0.1 release notes do not publish a support matrix, so read the require block in composer.json at the tag before committing. It assumes a conventional Laravel application on Eloquent with a service provider and publishable migrations. Confirm the illuminate/support and PHP constraints match your application before adding it to a production project.
- Does fulcrum-settings require a Laravel morph map?
- The package persists settings against an owning model through a polymorphic relation and resolves that owner through Laravel's Relation::morphMap(). Define your morph map before any settings are written, because rows stored under an alias and rows stored under a fully-qualified class name will not resolve to each other. Version 2.0.1 specifically fixes resolution of morph-map aliases, so pin at least that release.
- Can I use one settings key for global defaults, tenant overrides and per-entity overrides?
- Yes, this is the intended shape: a single lookup resolves global defaults first, then scoped overrides at tenant or entity level. The owning model is recorded polymorphically via settingable_type and settingable_id, so overrides attach to whichever model you scope to. The package also documents nullable ownership, which is how ownerless global-scope settings are represented.
- How does caching work in fulcrum-settings and how do I clear it?
- The package includes a cache layer in front of database reads so runtime configuration lookups stay cheap. Writes should invalidate the relevant cache entries, but verify this behaviour in your own integration tests rather than assuming it. After upgrading from 2.0.0, and after any backfill of setting rows, flush the cache so stale alias-keyed entries cannot survive the fix.
- Does fulcrum-settings support typed setting values such as booleans, integers and arrays?
- Yes, the package advertises typed values, which keep runtime configuration predictable instead of returning everything as a string. Cast values to the type you need, such as boolean for feature toggles or array for JSON-backed configuration blobs. Storing types deliberately matters most for flags evaluated in conditionals, where a string 'false' would otherwise be truthy.
- What was the morph-map bug in fulcrum-settings 2.0.0 and should I upgrade?
- Version 2.0.0 could fail to resolve aliased morph types when looking up settings, which typically produces no exception at all: reads silently fall back to defaults, or writes land under a type string a later read cannot match. Version 2.0.1 fixes that alias resolution and is a patch release with no public API changes. There is no reason to pin 2.0.0 under any circumstances.
- Do I need a data backfill when upgrading fulcrum-settings to 2.0.1?
- The patch repairs the resolution logic, not rows already written under a mismatched type, so remediation is on the consumer. Audit the settings value table by comparing distinct settingable_type values against your registered morph aliases and against fully-qualified class names. Any row whose type is an FQCN while the app registers an alias, or the reverse, is suspect and needs a one-off backfill before the fix is meaningful.
- Can fulcrum-settings do rule-based targeting and conditional evaluation for feature flags?
- Yes, the package positions itself as both a feature flag and configuration management system with rule-based targeting and conditional evaluation. That maps cleanly onto multi-tenant configuration precedence where defaults are overridden per tenant or per entity. It sits as a thin persistence and resolution layer, so it does not constrain your domain modelling.
- How do I test fulcrum-settings in a Laravel test suite?
- Use RefreshDatabase and seed the settings rows your test needs, defining the same morph map your application registers so alias resolution behaves identically to production. Assert both the resolved value and the fallback-to-default path, since silent default fallback is the failure mode the 2.0.1 fix addresses. Add a regression test around the morph path yourself if you rely on aliased owners, and clear the settings cache between tests that mutate values.
Weaver
How can I help you explore Laravel packages today?