Laravel Settings

A powerful, flexible global settings package for Laravel microservices. Manage application configurations with database persistence and optional caching support.

Overview

Laravel Settings provides a centralized way to manage application-wide settings in Laravel applications. Perfect for microservices architectures, it stores settings in a database table with built-in support for:

Database Persistence: Store settings securely in your database
Optional Caching: Leverage Redis or file caching for improved performance
JSON Support: Store complex data structures as JSON
Type Flexibility: Support for multiple data types (string, json, etc.)
Configuration Management: Easily customizable table names and cache behavior

Features

✨ Key Capabilities:

Store and retrieve global application settings
Support for both simple string values and complex JSON data
Configurable caching with multiple store options (Redis, File, etc.)
Automatic cache invalidation
Easy integration with Laravel's service container
ULID primary keys for modern database design
Full Laravel 10, 11, and 12 compatibility

Requirements

PHP 8.1 or higher
Laravel 10.0, 11.0, or 12.0
A relational database (MySQL, PostgreSQL, SQLite, etc.)

Installation

Via Composer

composer require vocabia/laravel-settings

The package will auto-register with Laravel's service provider discovery.

Publish Configuration

Publish the configuration file:

php artisan vendor:publish --tag=settings-config

Publish the migration:

php artisan vendor:publish --tag=settings-migrations

Run migrations:

php artisan migrate

Artisan Commands

Setup Commands

Publish Configuration Files

# Publish the settings configuration file
php artisan vendor:publish --tag=settings-config

# This creates config/vocabia_settings.php in your application

Publish and Run Migrations

# Publish database migrations
php artisan vendor:publish --tag=settings-migrations

# Run all pending migrations (including settings table)
php artisan migrate

# Run migrations with step-by-step feedback
php artisan migrate --step

# Rollback the last batch of migrations
php artisan migrate:rollback

# Rollback all migrations
php artisan migrate:reset

# Rollback all migrations and run them again
php artisan migrate:refresh

# Rollback and re-run all migrations with seeders
php artisan migrate:refresh --seed

Database Interaction via Tinker

# Open the interactive shell
php artisan tinker

# Inside tinker, you can manage settings:
>>> $setting = new \Vocabia\LaravelSettings\Models\VocabiaSettings();
>>> $setting->key = 'app_name';
>>> $setting->value = 'My Application';
>>> $setting->type = 'string';
>>> $setting->description = 'Application name';
>>> $setting->save();

# Or use create method:
>>> \Vocabia\LaravelSettings\Models\VocabiaSettings::create([
...     'key' => 'api_key',
...     'value' => 'secret-key-123',
...     'type' => 'string',
...     'description' => 'API Key'
... ]);

# Query settings:
>>> \Vocabia\LaravelSettings\Models\VocabiaSettings::all();
>>> \Vocabia\LaravelSettings\Models\VocabiaSettings::where('key', 'app_name')->first();

# Clear cache for a setting:
>>> app('setting')->clearCache('app_name');

Cache Management Commands

# Clear all cache
php artisan cache:clear

# Clear specific cache tags (settings)
php artisan cache:clear --tags

# Forget a specific cache key
php artisan cache:forget setting_app_name

# Flush all cache (Redis, File, etc.)
php artisan cache:flush

Development Commands

# Check the database status
php artisan db:show

# List all tables
php artisan db:table settings

# Create a backup before making changes
php artisan db:wipe

# View pending migrations
php artisan migrate:status

Model Inspection

# Open tinker to inspect the Settings model
php artisan tinker

# Show all columns in settings table
>>> \Vocabia\LaravelSettings\Models\VocabiaSettings::first()?->getAttributes();

# Count all settings
>>> \Vocabia\LaravelSettings\Models\VocabiaSettings::count();

# Get column information
>>> \Vocabia\LaravelSettings\Models\VocabiaSettings::all()->map(fn($s) => $s->only(['key', 'type', 'created_at']));

Practical Artisan Workflows

Initial Setup

# Install package
composer require vocabia/laravel-settings

# Publish configuration and migrations
php artisan vendor:publish --tag=settings-config
php artisan vendor:publish --tag=settings-migrations

# Run migrations to create settings table
php artisan migrate

# Verify table creation
php artisan db:table settings

Add New Settings via Tinker

php artisan tinker

# Add API rate limit setting
>>> \Vocabia\LaravelSettings\Models\VocabiaSettings::create([
...     'key' => 'api.rate_limit',
...     'value' => '1000',
...     'type' => 'string',
...     'description' => 'API requests per hour'
... ]);

# Add feature flags
>>> \Vocabia\LaravelSettings\Models\VocabiaSettings::create([
...     'key' => 'features.new_ui',
...     'json_value' => ['enabled' => true, 'beta' => false],
...     'type' => 'json',
...     'description' => 'New UI feature toggle'
... ]);

# Exit tinker
>>> exit

Update Settings and Clear Cache

php artisan tinker

# Update a setting
>>> $setting = \Vocabia\LaravelSettings\Models\VocabiaSettings::where('key', 'api.rate_limit')->first();
>>> $setting->update(['value' => '2000']);
>>> app('setting')->clearCache('api.rate_limit');

# Exit tinker
>>> exit

# Clear all settings cache
php artisan cache:clear

Export/Backup Settings

# Inside tinker, export all settings to JSON
php artisan tinker

>>> $settings = \Vocabia\LaravelSettings\Models\VocabiaSettings::all()
...     ->map(fn($s) => ['key' => $s->key, 'value' => $s->value, 'type' => $s->type])
...     ->toJson();
>>> file_put_contents('settings_backup.json', $settings);

Configuration

The configuration file is located at config/settings.php. Here's what you can customize:

return [
    // The database table name for storing settings
    'table_name' => 'settings',

    // Cache configuration
    'cache' => [
        'enabled' => true,           // Enable/disable caching
        'store'   => 'redis',        // Cache store (redis, file, etc.)
        'ttl'     => 3600,           // Time to live in seconds (1 hour)
        'prefix'  => 'setting_',     // Cache key prefix
    ],
];

Usage

Getting a Setting

use Vocabia\LaravelSettings\Services\VocabiaSettingService;

$settingService = app('setting');

// Get a setting with default value
$value = $settingService->get('app_name', 'My App');

// Get a setting without default
$value = $settingService->get('api_key');

Creating a Setting

use Vocabia\LaravelSettings\Models\VocabiaSettings;

// Store a simple string value
VocabiaSettings::create([
    'key' => 'app_name',
    'value' => 'My Application',
    'type' => 'string',
    'description' => 'Application name',
]);

// Store a JSON value
VocabiaSettings::create([
    'key' => 'feature_flags',
    'json_value' => [
        'new_ui' => true,
        'beta_api' => false,
    ],
    'type' => 'json',
    'description' => 'Feature flags configuration',
]);

Updating a Setting

$setting = Settings::where('key', 'app_name')->first();
$setting->update([
    'value' => 'Updated App Name',
]);

// Clear cache after update
$settingService->clearCache('app_name');

Deleting a Setting

Settings::where('key', 'app_name')->delete();

// Clear cache
$settingService->clearCache('app_name');

Facade Usage (Optional)

Create a facade for easier access:

// In your service provider or config/app.php aliases
'Setting' => Vocabia\LaravelSettings\Facades\SettingFacade::class,

// Usage
Setting::get('app_name');

Database Schema

The settings table includes the following columns:

Column	Type	Description
`id`	ULID	Primary key
`key`	String	Unique setting identifier (indexed)
`value`	Text	String value for the setting
`json_value`	JSONB	JSON value for complex data
`description`	String	Setting description
`type`	String	Data type (string, json, etc.)
`created_at`	Timestamp	Creation timestamp
`updated_at`	Timestamp	Update timestamp

Cache Configuration

Enable/Disable Caching

// config/vocabia_settings.php
'cache' => [
    'enabled' => false, // Disable caching
    // ...
],

Using Different Cache Stores

// config/vocabia_settings.php
'cache' => [
    'enabled' => true,
    'store' => 'redis',    // Use Redis
    'ttl' => 3600,
    'prefix' => 'setting_',
],

// Or use file cache
'store' => 'file',

Cache Prefix

Customize the cache key prefix to avoid conflicts:

'cache' => [
    'prefix' => 'app_settings_',
],

Advanced Usage

Retrieving JSON Settings

$settings = app('setting');

// Get JSON value as array
$flags = $settings->get('feature_flags');
// Returns: ['new_ui' => true, 'beta_api' => false]

// Update JSON value
$setting = Settings::where('key', 'feature_flags')->first();
$setting->json_value = ['new_ui' => true, 'beta_api' => true];
$setting->save();
$settings->clearCache('feature_flags');

Querying Settings

// Get all settings
$allSettings = Settings::all();

// Filter by type
$jsonSettings = Settings::where('type', 'json')->get();

// Search by key
$setting = Settings::where('key', 'like', '%api%')->first();

// Paginate settings
$paginated = Settings::paginate(15);

Best Practices

Use Descriptive Keys: Use clear, hierarchical naming for settings keys
```
'mail.smtp.host'
'features.new_dashboard'
'api.rate_limit'
```

Document Your Settings: Always include descriptions

Settings::create([
    'key' => 'api.rate_limit',
    'value' => '1000',
    'description' => 'API rate limit per hour',
]);

Cache Strategic Settings: Cache frequently accessed settings

'cache' => [
    'enabled' => true,
    'ttl' => 86400, // Cache for 24 hours
]

Invalidate Cache Appropriately: Always clear cache when updating

$setting->update(['value' => $newValue]);
$settingService->clearCache($setting->key);

Use Type Field: Indicate the setting type for clarity
```
'type' => 'string', 'json', 'boolean', etc.
```

Performance Considerations

Caching: Enable caching with Redis for optimal performance in production
TTL: Adjust cache TTL based on how frequently settings change
Database Indexes: The key column is indexed for fast lookups
ULID Keys: Uses ULID for better database performance vs UUID

Quick Command Reference

Task	Command
Installation & Setup
Install package	`composer require vocabia/laravel-settings`
Publish config	`php artisan vendor:publish --tag=settings-config`
Publish migrations	`php artisan vendor:publish --tag=settings-migrations`
Run migrations	`php artisan migrate`
Database & Migrations
Migrate with steps	`php artisan migrate --step`
Rollback last batch	`php artisan migrate:rollback`
Migration status	`php artisan migrate:status`
View table schema	`php artisan db:table settings`
Settings Management (via Tinker)
Open interactive shell	`php artisan tinker`
Create new setting	`\Vocabia\LaravelSettings\Models\VocabiaSettings::create([...])`
Get all settings	`\Vocabia\LaravelSettings\Models\VocabiaSettings::all()`
Query by key	`\Vocabia\LaravelSettings\Models\VocabiaSettings::where('key', 'name')->first()`
Count settings	`\Vocabia\LaravelSettings\Models\VocabiaSettings::count()`
Delete setting	`\Vocabia\LaravelSettings\Models\VocabiaSettings::where('key', 'name')->delete()`
Cache Management
Clear all cache	`php artisan cache:clear`
Flush cache completely	`php artisan cache:flush`
Forget specific key	`php artisan cache:forget setting_app_name`
Clear cache with tags	`php artisan cache:clear --tags`

Troubleshooting

Settings Not Updating

Ensure cache is cleared after updates:

$settingService->clearCache('your_key');

Or via artisan:

php artisan cache:clear

Wrong Cache Store

Verify the cache store exists in your config/cache.php:

'redis' => [
    'client' => env('REDIS_CLIENT', 'phpredis'),
    'connection' => 'default',
],

Migration Issues

Ensure migrations are published and run:

php artisan vendor:publish --tag=settings-migrations
php artisan migrate

Check migration status:

php artisan migrate:status

Table Not Found

If you get a "table not found" error when running migrations:

# Publish the migrations if not already done
php artisan vendor:publish --tag=settings-migrations

# Run pending migrations
php artisan migrate

# Verify the table was created
php artisan db:table settings

Tinker Command Not Found

Ensure Laravel Tinker is installed:

composer require laravel/tinker
php artisan tinker

Configuration Not Loaded

If the configuration is not being loaded properly:

# Clear config cache
php artisan config:clear

# Republish the configuration
php artisan vendor:publish --tag=settings-config --force

# Clear application cache
php artisan cache:clear

Settings Cached Incorrectly

To clear all settings-related cache entries:

php artisan tinker
>>> app('setting')->clearCache('*')
>>> exit

# Or use artisan
php artisan cache:flush

API Reference

SettingService

`get($key, $default = null)`

Retrieves a setting value with optional default.

Parameters:

$key (string): The setting key
$default (mixed): Default value if not found

Returns: The setting value or default

`clearCache($key)`

Clears the cache for a specific setting.