# rajeshmk/laravel-settings architecture

> Architecture diagram of the GitHub repository rajeshmk/laravel-settings, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rajeshmk/laravel-settings
- Repository: https://github.com/rajeshmk/laravel-settings

## Overview

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: [`src/Managers/SettingsManager.php`](https://github.com/rajeshmk/laravel-settings/blob/main/src/Managers/SettingsManager.php) (Settings Manager), [`src/Repositories/DatabaseSettingsRepository.php`](https://github.com/rajeshmk/laravel-settings/blob/main/src/Repositories/DatabaseSettingsRepository.php) (Database Repo), [`src/SettingsServiceProvider.php`](https://github.com/rajeshmk/laravel-settings/blob/main/src/SettingsServiceProvider.php) (Service Provider), [`src/Contracts/SettingsRepository.php`](https://github.com/rajeshmk/laravel-settings/blob/main/src/Contracts/SettingsRepository.php) (Repository Contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_framework["Framework API"]
  node_src_weak_provider["Service Provider<br/>laravel provider"]
  node_src_helpers["Helper<br/>[helpers.php]"]
  node_src_facade_settings["Settings Facade<br/>[Settings.php]"]
  node_src_trait_has_settings["HasSettings<br/>model trait<br/>[HasSettings.php]"]
end

subgraph group_core["Core Settings"]
  node_src_contract_manager["Manager Contract<br/>interface"]
  node_src_manager_settings["Settings Manager<br/>orchestrator"]
  node_src_contract_scope["Scope Contract<br/>interface<br/>[SettingsScope.php]"]
  node_src_resolver_scope_hierarchy["Scope Resolver<br/>hierarchy resolver"]
  node_src_resolver_value_caster["Value Caster<br/>type caster<br/>[ValueCaster.php]"]
  node_src_contract_repository["Repository Contract<br/>interface"]
end

subgraph group_persistence["Persistence"]
  node_src_repo_cached["Cached Repo<br/>cache repository"]
  node_src_repo_database["Database Repo"]
  node_src_model_definition[("Setting Definition<br/>Eloquent model")]
  node_src_model_value[("Setting Value<br/>Eloquent model<br/>[SettingValue.php]")]
  node_db_migration_definitions["Definitions Migration<br/>schema migration"]
  node_db_migration_values["Values Migration<br/>schema migration"]
end

subgraph group_support["Support"]
  node_src_support_scope(("Scope Value<br/>[Scope.php]"))
  node_src_exception_validation{{"Validation Error<br/>domain exception"}}
end

node_src_weak_provider -->|"binds"| node_src_manager_settings
node_src_weak_provider -->|"aliases"| node_src_facade_settings
node_src_weak_provider -->|"loads"| node_src_helpers
node_src_helpers -->|"calls"| node_src_manager_settings
node_src_facade_settings -->|"forwards"| node_src_manager_settings
node_src_trait_has_settings -->|"uses"| node_src_contract_scope
node_src_trait_has_settings -->|"returns"| node_src_manager_settings
node_src_manager_settings -->|"resolves"| node_src_resolver_scope_hierarchy
node_src_manager_settings -->|"reads/writes"| node_src_contract_repository
node_src_manager_settings -->|"casts"| node_src_resolver_value_caster
node_src_manager_settings -->|"throws"| node_src_exception_validation
node_src_resolver_scope_hierarchy -->|"orders"| node_src_support_scope
node_src_repo_cached -->|"wraps"| node_src_repo_database
node_src_repo_database -->|"loads"| node_src_model_definition
node_src_repo_database -->|"loads"| node_src_model_value
node_src_model_definition -->|"maps to"| node_db_migration_definitions
node_src_model_value -->|"maps to"| node_db_migration_values
node_src_repo_database -->|"implements"| node_src_contract_repository
node_src_repo_cached -->|"implements"| node_src_contract_repository
node_src_contract_scope -->|"describes"| node_src_support_scope
node_src_resolver_value_caster -->|"validates"| node_src_exception_validation

click node_src_weak_provider "https://github.com/rajeshmk/laravel-settings/blob/main/src/SettingsServiceProvider.php"
click node_src_helpers "https://github.com/rajeshmk/laravel-settings/blob/main/src/helpers.php"
click node_src_facade_settings "https://github.com/rajeshmk/laravel-settings/blob/main/src/Facades/Settings.php"
click node_src_trait_has_settings "https://github.com/rajeshmk/laravel-settings/blob/main/src/Traits/HasSettings.php"
click node_src_contract_manager "https://github.com/rajeshmk/laravel-settings/blob/main/src/Contracts/SettingsManager.php"
click node_src_manager_settings "https://github.com/rajeshmk/laravel-settings/blob/main/src/Managers/SettingsManager.php"
click node_src_contract_scope "https://github.com/rajeshmk/laravel-settings/blob/main/src/Contracts/SettingsScope.php"
click node_src_resolver_scope_hierarchy "https://github.com/rajeshmk/laravel-settings/blob/main/src/Resolvers/ScopeHierarchyResolver.php"
click node_src_resolver_value_caster "https://github.com/rajeshmk/laravel-settings/blob/main/src/Resolvers/ValueCaster.php"
click node_src_contract_repository "https://github.com/rajeshmk/laravel-settings/blob/main/src/Contracts/SettingsRepository.php"
click node_src_repo_cached "https://github.com/rajeshmk/laravel-settings/blob/main/src/Repositories/CachedSettingsRepository.php"
click node_src_repo_database "https://github.com/rajeshmk/laravel-settings/blob/main/src/Repositories/DatabaseSettingsRepository.php"
click node_src_model_definition "https://github.com/rajeshmk/laravel-settings/blob/main/src/Models/SettingDefinition.php"
click node_src_model_value "https://github.com/rajeshmk/laravel-settings/blob/main/src/Models/SettingValue.php"
click node_db_migration_definitions "https://github.com/rajeshmk/laravel-settings/blob/main/database/migrations/2026_05_12_000001_create_setting_definitions_table.php"
click node_db_migration_values "https://github.com/rajeshmk/laravel-settings/blob/main/database/migrations/2026_05_12_000002_create_setting_values_table.php"
click node_src_support_scope "https://github.com/rajeshmk/laravel-settings/blob/main/src/Support/Scope.php"
click node_src_exception_validation "https://github.com/rajeshmk/laravel-settings/blob/main/src/Exceptions/SettingsValidationException.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_weak_provider,node_src_helpers,node_src_facade_settings,node_src_trait_has_settings toneBlue
class node_src_contract_manager,node_src_manager_settings,node_src_contract_scope,node_src_resolver_scope_hierarchy,node_src_resolver_value_caster,node_src_contract_repository toneAmber
class node_src_repo_cached,node_src_repo_database,node_src_model_definition,node_src_model_value,node_db_migration_definitions,node_db_migration_values toneMint
class node_src_support_scope,node_src_exception_validation toneRose
```

## Components

### Framework API

Laravel entry points and container wiring

- [Service Provider](https://github.com/rajeshmk/laravel-settings/blob/main/src/SettingsServiceProvider.php): laravel provider · Registers bindings, facade alias, and package services · `src/SettingsServiceProvider.php`
- [Helper](https://github.com/rajeshmk/laravel-settings/blob/main/src/helpers.php): global helper · Convenience entry point for the settings manager · `src/helpers.php`
- [Settings Facade](https://github.com/rajeshmk/laravel-settings/blob/main/src/Facades/Settings.php): facade · Static API over the shared settings manager · `src/Facades/Settings.php`
- [HasSettings](https://github.com/rajeshmk/laravel-settings/blob/main/src/Traits/HasSettings.php): model trait · Adds scoped settings access to Eloquent models · `src/Traits/HasSettings.php`

### Core Settings

Manager, contracts, scope resolution, and casting

- [Manager Contract](https://github.com/rajeshmk/laravel-settings/blob/main/src/Contracts/SettingsManager.php): interface · Public contract for the settings manager · `src/Contracts/SettingsManager.php`
- [Settings Manager](https://github.com/rajeshmk/laravel-settings/blob/main/src/Managers/SettingsManager.php): orchestrator · Coordinates scope fallback, storage access, and casting · `src/Managers/SettingsManager.php`
- [Scope Contract](https://github.com/rajeshmk/laravel-settings/blob/main/src/Contracts/SettingsScope.php): interface · Represents a settings scope provider · `src/Contracts/SettingsScope.php`
- [Scope Resolver](https://github.com/rajeshmk/laravel-settings/blob/main/src/Resolvers/ScopeHierarchyResolver.php): hierarchy resolver · Builds ordered fallback chains from the current scope · `src/Resolvers/ScopeHierarchyResolver.php`
- [Value Caster](https://github.com/rajeshmk/laravel-settings/blob/main/src/Resolvers/ValueCaster.php): type caster · Converts stored values to and from runtime types · `src/Resolvers/ValueCaster.php`
- [Repository Contract](https://github.com/rajeshmk/laravel-settings/blob/main/src/Contracts/SettingsRepository.php): interface · Storage boundary for settings persistence · `src/Contracts/SettingsRepository.php`

### Persistence

Repositories, models, and migrations for stored settings

- [Cached Repo](https://github.com/rajeshmk/laravel-settings/blob/main/src/Repositories/CachedSettingsRepository.php): cache repository · Cache-backed reads with per-key invalidation · `src/Repositories/CachedSettingsRepository.php`
- [Database Repo](https://github.com/rajeshmk/laravel-settings/blob/main/src/Repositories/DatabaseSettingsRepository.php): database repository · Direct persistence implementation for settings data · `src/Repositories/DatabaseSettingsRepository.php`
- [Setting Definition](https://github.com/rajeshmk/laravel-settings/blob/main/src/Models/SettingDefinition.php): Eloquent model · Setting metadata such as key, type, and default · `src/Models/SettingDefinition.php`
- [Setting Value](https://github.com/rajeshmk/laravel-settings/blob/main/src/Models/SettingValue.php): Eloquent model · Scoped stored value for a setting key · `src/Models/SettingValue.php`
- [Definitions Migration](https://github.com/rajeshmk/laravel-settings/blob/main/database/migrations/2026_05_12_000001_create_setting_definitions_table.php): schema migration · Creates the setting_definitions table · `database/migrations/2026_05_12_000001_create_setting_definitions_table.php`
- [Values Migration](https://github.com/rajeshmk/laravel-settings/blob/main/database/migrations/2026_05_12_000002_create_setting_values_table.php): schema 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](https://github.com/rajeshmk/laravel-settings/blob/main/src/Support/Scope.php): scope value object · Internal representation of scope identity and type · `src/Support/Scope.php`
- [Validation Error](https://github.com/rajeshmk/laravel-settings/blob/main/src/Exceptions/SettingsValidationException.php): domain exception · Raised for invalid setting input or inconsistent state · `src/Exceptions/SettingsValidationException.php`

## Connections

- 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