Weave Code
Laravel Settings Laravel Package
spatie/laravel-settings
Strongly typed application settings for Laravel. Define settings classes with typed properties, store values in a repository (database, Redis, etc.), inject settings via the container, and update them easily with $settings->save().
Store your application settings
Frequently asked questions about Laravel Settings
- How do I migrate existing settings from .env or config files to spatie/laravel-settings?
- Start by creating a Settings class for each config group, then manually seed the database using a data migration. Use `Settings::create()` or `Settings::update()` in a migration file to populate initial values. For complex data, consider writing a script to extract values from .env or config files and map them to your new settings classes.
- Can I use this package with Laravel 9 or older versions?
- No, this package requires Laravel 8+ and PHP 8.0+. The type system and dependency injection features used by the package aren’t fully supported in older Laravel versions. If you’re on Laravel 7 or below, consider alternatives like `laravel-settings` by other authors or manual database-backed configuration.
- How do I validate settings updates before saving?
- Use Laravel’s built-in validation by creating a Form Request class (e.g., `GeneralSettingsRequest`) that extends `FormRequest`. Override the `rules()` method to define validation rules for each setting field. Inject this request into your update method alongside the Settings class, and Laravel will automatically validate inputs before they reach your controller.
- What’s the best way to handle multi-tenant settings?
- Extend the default repository to include a `tenant_id` column and override the `findOrCreate()` method to scope queries by tenant. Alternatively, use a separate Settings class per tenant (e.g., `Tenant1GeneralSettings`, `Tenant2GeneralSettings`) and register them dynamically based on the current tenant. Cache settings per tenant to avoid repeated database lookups.
- How do I cache settings for performance without losing real-time updates?
- Enable caching by setting `SETTINGS_CACHE_ENABLED=true` in your `.env` and configure the cache driver (e.g., `redis`, `file`). Use a short TTL (e.g., 5 minutes) for frequently updated settings or disable caching for critical configurations. Listen to the `settings.saved` event to invalidate cache manually when settings are updated programmatically.
- Can I use Redis as the primary storage instead of the database?
- No, Redis is only supported as a cache layer, not as primary storage. The package uses the database as the source of truth for settings, with Redis acting as a read-through cache. If you need Redis for persistence, consider building a custom repository or using a package like `spatie/laravel-redis-settings` as an alternative.
- How do I test settings updates in PHPUnit or PEST?
- Mock the Settings class in your tests using Laravel’s mocking tools. For example, in PHPUnit, use `$this->partialMock(GeneralSettings::class, [], function ($mock) { ... })` to simulate updates. Alternatively, create test factories to seed settings before each test. Use `Settings::fake()` if the package provides a testing helper to isolate settings logic.
- What happens if I forget to run a settings migration in production?
- The package will throw a runtime error when accessing missing settings, as it expects the database schema to match your Settings classes. To prevent this, add a pre-deploy check in your CI/CD pipeline (e.g., a script that runs `php artisan settings:migrate` and fails if migrations are pending). For critical settings, include a fallback mechanism (e.g., default values in the Settings class).
- How do I add custom data types (e.g., DateTime, arrays, or DTOs) to settings?
- Use Laravel’s global casts or define custom accessors/mutators in your Settings class. For example, add `protected $casts = ['published_at' => 'datetime']` to automatically cast a string to a Carbon instance. For complex types like DTOs, serialize/deserialize manually in `getAttribute()` and `setAttribute()` methods or use a custom encoder/decoder via the repository.
- Are there alternatives to spatie/laravel-settings for Laravel?
- Yes, alternatives include `beberlei/attributes` (for attribute-based settings), `laravel-settings` by other authors (often simpler but less type-safe), or rolling your own solution with Eloquent models and caching. For Redis-only storage, consider `spatie/laravel-redis-settings` or `laravel-redis-settings`. Evaluate based on your needs: this package excels in type safety and Laravel integration but requires migrations.
Weaver
How can I help you explore Laravel packages today?