How rajeshmk/laravel-settings works
1. What this package is
- This is a Laravel package that adds a settings subsystem to an application, centered on hierarchical, multi-scope settings.
- It is not a standalone app; its architecture is built around Laravel’s service container, facades, Eloquent models, migrations, and package service provider.
2. Primary entry points
- There are three ways callers interact with the package:
- the settings() helper,
- the Settings facade,
- the HasSettings trait on Eloquent models.
- All of these route into the same core manager, so the package has a single behavioral center.
3. Core orchestration layer
- src/Managers/SettingsManager.php is the main orchestrator.
- It exposes the public API: get, set, has, forget, all, and scope(...).
- The manager is responsible for combining scope resolution, repository access, and value casting into one coherent read/write flow.
4. Scope model and hierarchy
- Scoping is abstracted behind Contracts/SettingsScope.
- Application models that support scoped settings implement this contract and typically use Traits/HasSettings.
- Resolvers/ScopeHierarchyResolver.php is the mechanism that turns a current scope into an ordered fallback chain, such as User -> Team -> Company -> Global.
- The scope object itself is represented in Support/Scope.php, which acts as the internal value object for scope identity/type.
5. Data access boundaries
- Persistence is split behind Contracts/SettingsRepository.
- There are two repository implementations:
- Repositories/DatabaseSettingsRepository.php for raw database access,
- Repositories/CachedSettingsRepository.php for cache-backed reads with invalidation.
- This is the key boundary between the package’s domain logic and storage concerns.
6. Caching behavior
- Cached reads are layered on top of the database repository rather than replacing it.
- The cache layer is intended to serve repeated reads quickly and invalidate selectively when a setting changes.
- The README indicates per-key invalidation on set() and forget(), so cache consistency is managed at the setting-key level rather than by broad flushes.
7. Persistence schema
- The package uses two tables:
- setting_definitions for the setting key, type, and default metadata,
- setting_values for concrete stored values tied to a specific scope.
- The migrations in database/migrations define this split, which separates definition metadata from scope-specific values.
- The model classes Models/SettingDefinition.php and Models/SettingValue.php represent those tables in Eloquent.
8. Casting and type handling
- Resolvers/ValueCaster.php handles conversion between stored values and runtime types.
- Supported types include integer, float, boolean, array, object, json, and string.
- The package infers or validates types around writes and ensures values come back in app-friendly form on reads.
- Exceptions/SettingsValidationException.php marks invalid input or inconsistent setting state as a domain-level error.
9. Read/write flow
- On set(), the manager writes a scoped value, ensures a definition exists if needed, and invalidates the relevant cache entry.
- On get(), the manager walks the resolved scope chain until it finds a value, then casts it before returning it.
- If no value exists anywhere in the chain, the manager returns the caller-supplied default.
10. Model integration boundary
- Traits/HasSettings is the integration point for domain models like User, Team, or Company.
- It lets a model expose a scoped settings manager while also defining fallback scopes through getSettingsFallbackScopes().
- This makes the package work as an application-level capability rather than requiring callers to manually manage scope objects.
11. Framework wiring
- SettingsServiceProvider.php registers bindings, the facade alias, helper access, and package services into Laravel’s container.
- src/helpers.php provides the global helper entry point.
- src/Facades/Settings.php provides the static-looking API over the same underlying manager.
12. Repository quality signals
- Unit tests cover the most important pure logic boundaries:
- DatabaseSettingsRepositoryTest,
- ScopeHierarchyResolverTest,
- ValueCasterTest.
- That test split reflects the architecture: storage, hierarchy resolution, and casting are the three main technical axes of the package.
Main entry points: SettingsManager.php Settings Manager · DatabaseSettingsRepository.php Database Repo · SettingsServiceProvider.php Service Provider · SettingsRepository.php Repository Contract
Components 18
Framework API
Laravel entry points and container wiring
- Service Provider · Registers bindings, facade alias, and package services
src/SettingsServiceProvider.php - Helper · Convenience entry point for the settings manager
src/helpers.php - Settings Facade · Static API over the shared settings manager
src/Facades/Settings.php - HasSettings · Adds scoped settings access to Eloquent models
src/Traits/HasSettings.php
Core Settings
Manager, contracts, scope resolution, and casting
- Manager Contract · Public contract for the settings manager
src/Contracts/SettingsManager.php - Settings Manager · Coordinates scope fallback, storage access, and casting
src/Managers/SettingsManager.php - Scope Contract · Represents a settings scope provider
src/Contracts/SettingsScope.php - Scope Resolver · Builds ordered fallback chains from the current scope
src/Resolvers/ScopeHierarchyResolver.php - Value Caster · Converts stored values to and from runtime types
src/Resolvers/ValueCaster.php - Repository Contract · Storage boundary for settings persistence
src/Contracts/SettingsRepository.php
Persistence
Repositories, models, and migrations for stored settings
- Cached Repo · Cache-backed reads with per-key invalidation
src/Repositories/CachedSettingsRepository.php - Database Repo · Direct persistence implementation for settings data
src/Repositories/DatabaseSettingsRepository.php - Setting Definition · Setting metadata such as key, type, and default
src/Models/SettingDefinition.php - Setting Value · Scoped stored value for a setting key
src/Models/SettingValue.php - Definitions Migration · Creates the setting_definitions table
database/migrations/2026_05_12_000001_create_setting_definitions_table.php - Values Migration · Creates the setting_values table
database/migrations/2026_05_12_000002_create_setting_values_table.php
Support
Shared value objects and domain exceptions
- Scope Value · Internal representation of scope identity and type
src/Support/Scope.php - Validation Error · Raised for invalid setting input or inconsistent state
src/Exceptions/SettingsValidationException.php
Connections 21
- Service Provider → Settings Manager: binds · Registers the manager in the container
- Service Provider → Settings Facade: aliases · Exposes the facade entry point
- Service Provider → Helper: loads · Makes the helper available to applications
- Helper → Settings Manager: calls · Returns the shared manager instance
- Settings Facade → Settings Manager: forwards · Static calls resolve to the manager
- HasSettings → Scope Contract: uses · Model instances act as scope providers
- HasSettings → Settings Manager: returns · Exposes scoped settings access from models
- Settings Manager → Scope Resolver: resolves · Builds fallback chains for reads
- Settings Manager → Repository Contract: reads/writes · Delegates persistence through the storage boundary
- Settings Manager → Value Caster: casts · Normalizes values on read and write
- Settings Manager → Validation Error: throws · Signals invalid setting state
- Scope Resolver → Scope Value: orders · Produces an ordered chain of scopes
- Cached Repo → Database Repo: wraps · Uses the database repository as the backing store
- Database Repo → Setting Definition: loads · Reads setting metadata from Eloquent
- Database Repo → Setting Value: loads · Reads and writes scoped values
- Setting Definition → Definitions Migration: maps to · Definition model matches its table schema
- Setting Value → Values Migration: maps to · Value model matches its table schema
- Database Repo → Repository Contract: implements · Concrete storage implementation
- Cached Repo → Repository Contract: implements · Cache-aware repository implementation
- Scope Contract → Scope Value: describes · Scope providers resolve to internal scope objects
- Value Caster → Validation Error: validates · Raises errors for unsupported or inconsistent types