README

An advanced settings management plugin for FilamentPHP v4 with encryption, caching, audit trails, and import/export capabilities.

✨ Features

🔐 Security: Automatic encryption for sensitive settings with field-level validation
⚡ Performance: Multi-layer caching with memory and Laravel cache optimization
📊 Organization: Dynamic grouping, categories, and hierarchical settings
🔄 Import/Export: Multiple formats (JSON, YAML, CSV) with backup/restore
📈 Audit Trail: Complete change history with user tracking and rollback
🎨 FilamentPHP: Rich form components with tabs and dynamic schemas

📦 Installation

Install the package via Composer:

composer require iamjohndev/prism-settings

Publish and run the migrations:

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

Optionally, publish the config file:

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

⚙️ Configuration

Add the plugin to your Filament panel:

use Vendor\PrismSettings\PrismSettingsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            PrismSettingsPlugin::make(),
        ]);
}

🛠️ Basic Usage

Creating a Settings Class

Create a settings class by extending BaseSettings:

<?php

namespace App\Settings;

use Filament\Forms;
use Filament\Forms\Components\Tabs;
use Vendor\PrismSettings\Settings\BaseSettings;

class AppSettings extends BaseSettings
{
    protected string $group = 'app';
    protected ?string $navigationIcon = 'heroicon-o-cog-6-tooth';
    protected ?string $title = 'Application Settings';

    public function schema(): array
    {
        return [
            Tabs::make('Application Settings')
                ->schema([
                    Tabs\Tab::make('General')
                        ->schema([
                            Forms\Components\TextInput::make('name')
                                ->label('Application Name')
                                ->required()
                                ->maxLength(255),
                            
                            Forms\Components\Toggle::make('maintenance_mode')
                                ->label('Maintenance Mode'),
                        ]),
                    
                    Tabs\Tab::make('Email')
                        ->schema([
                            Forms\Components\TextInput::make('mail_from_address')
                                ->label('From Email')
                                ->email()
                                ->required(),
                        ]),
                ]),
        ];
    }
}

Creating a Settings Page

Create a Filament page for your settings:

<?php

namespace App\Filament\Pages;

use App\Settings\AppSettings;
use Vendor\PrismSettings\Pages\BaseSettingsPage;
use Vendor\PrismSettings\Settings\BaseSettings;

class AppSettingsPage extends BaseSettingsPage
{
    protected static ?string $navigationIcon = 'heroicon-o-cog-6-tooth';
    protected static string $routePath = '/app-settings';
    protected static ?string $navigationLabel = 'App Settings';

    public function getSettings(): BaseSettings
    {
        return new AppSettings();
    }
}

public function panel(Panel $panel): Panel
{
    return $panel
        ->pages([
            \App\Filament\Pages\AppSettingsPage::class,
        ]);
}

🎯 Advanced Usage

Using the Settings Manager

Inject the SettingsManager to programmatically manage settings:

use Vendor\PrismSettings\SettingsManager;

class SomeController
{
    public function __construct(private SettingsManager $settings) {}

    public function index()
    {
        // Get a setting value
        $appName = $this->settings->get('app', 'name', 'Default App');
        
        // Set a setting value
        $this->settings->set('app', 'name', 'New App Name');
        
        // Get all settings in a group
        $appSettings = $this->settings->getGroup('app');
        
        // Set with advanced options
        $this->settings->set('app', 'api_key', 'secret-key', [
            'encrypted' => true,
            'validation_rules' => ['required', 'string', 'min:20'],
            'description' => 'API key for external service',
        ]);
    }
}

Encryption and Validation

Settings can be automatically encrypted and validated:

// In your settings schema
Forms\Components\TextInput::make('api_key')
    ->label('API Key')
    ->password()
    ->required()
    ->minLength(20)
    ->helperText('This will be encrypted automatically'),

The plugin will automatically:

Extract validation rules from form components
Encrypt sensitive fields (password, API keys, etc.)
Store validation rules for runtime checking

Caching

Settings are automatically cached for performance. Configure caching in config/prism-settings.php:

'cache' => [
    'enabled' => true,
    'ttl' => 3600, // 1 hour
    'warm_up_groups' => ['app', 'mail'], // Auto-load these groups
],

Manually manage cache:

use Vendor\PrismSettings\Services\SettingsCache;

// Preload specific groups
SettingsCache::preload(['app', 'mail']);

// Warm up cache
SettingsCache::warmUp();

// Clear cache
SettingsCache::flush();

🔄 Import/Export

Using the UI

The settings pages include built-in import/export actions in the header.

Using CLI Commands

# Export settings
php artisan prism-settings:export --groups=app,mail --format=json

# Import settings
php artisan prism-settings:import backup.json --overwrite

# Create backup
php artisan prism-settings:backup --groups=app

# Restore from backup
php artisan prism-settings:restore backup.json --force

Programmatic Import/Export

use Vendor\PrismSettings\Services\SettingsImportExport;

$service = app(SettingsImportExport::class);

// Export to array
$data = $service->export(['app', 'mail']);

// Export to file
$path = $service->exportToFile(['app'], [
    'format' => 'json',
    'include_encrypted' => false,
]);

// Import from file
$result = $service->importFromFile('settings.json', [
    'overwrite' => true,
    'skip_errors' => false,
]);

📊 Settings Groups and Categories

Organize settings with groups and categories:

use Vendor\PrismSettings\SettingsManager;

$manager = app(SettingsManager::class);

// Register settings in groups
$manager->register(new AppSettings());
$manager->register(new MailSettings());

// Create custom categories
$manager->group('Application')
    ->add('app')
    ->add('cache')
    ->icon('heroicon-o-cog-6-tooth')
    ->label('Application Settings')
    ->description('Core application configuration');

🔍 Audit Trail and History

View and manage settings history through the built-in History resource, or programmatically:

use Vendor\PrismSettings\Models\PrismSetting;

// Get setting with history
$setting = PrismSetting::with('history')->find(1);

// Revert to previous value
$history = $setting->history()->latest()->first();
$setting->update(['value' => $history->old_value]);

🎨 Customization

Custom Field Types

Extend the base settings to support custom field types:

protected function getComponentType($component): string
{
    return match (true) {
        $component instanceof MyCustomComponent => 'custom',
        default => parent::getComponentType($component),
    };
}

Custom Validation

Add custom validation to settings:

public function schema(): array
{
    return [
        Forms\Components\TextInput::make('domain')
            ->rules(['required', 'url', new ValidDomain()]),
    ];
}

Events

Listen for settings changes:

use Vendor\PrismSettings\Events\SettingsUpdated;

Event::listen(SettingsUpdated::class, function ($event) {
    // Clear related caches
    if ($event->group === 'app' && $event->key === 'name') {
        Cache::forget('app_title');
    }
});

📋 Configuration Options

Key configuration options in config/prism-settings.php:

return [
    'defaults' => [
        'app' => [
            'name' => env('APP_NAME', 'Laravel'),
            // ... other defaults
        ],
    ],
    
    'cache' => [
        'enabled' => true,
        'ttl' => 3600,
        'warm_up_groups' => ['app'],
    ],
    
    'security' => [
        'encrypt_sensitive' => true,
        'audit_changes' => true,
        'require_permission' => 'manage-settings',
    ],
    
    'export' => [
        'formats' => ['json', 'yaml', 'csv'],
        'include_encrypted_by_default' => false,
    ],
];

🔒 Security

🔐 Encryption: Sensitive settings are automatically encrypted
🛡️ Permissions: Configure required permissions for settings management
📝 Audit Trail: All changes are logged with user and IP tracking
✅ Validation: Runtime validation prevents invalid settings

📈 Performance

🚀 Multi-layer Caching: Memory + Laravel cache for optimal performance
⚡ Preloading: Load commonly used settings on application boot
🎯 Lazy Loading: Settings are only loaded when accessed
🔥 Cache Warming: Proactively cache frequently accessed settings

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This package is open-sourced software licensed under the MIT license.

🆘 Support

For support, please open an issue on GitHub or contact the maintainers.

Built with ❤️ for FilamentPHP v4

iamjohndev / prism-settings

Maintainers

Details