README

A production-ready, highly architecture-focused reusable Filament Settings plugin powered by spatie/laravel-settings. Built specifically for modern Filament v5 and Laravel applications.

Features

⚙️ Single Filament Settings Page: Clean, unified navigation page with persisable tabs in URL query strings.
🧩 Built-in Default Tabs: Includes pre-configured General Settings, Social Links (with dynamic repeaters), and Static Pages (Privacy Policy, Terms, About).
🗂️ Nested Sub-Tabs: Support for main tabs, nested sub-tabs, and dynamic dynamic child registration.
🌐 Multilingual/Locale Tabs: Sub-tabs can be marked translatable, automatically rendering tabbed interfaces for each configured locale with RTL support.
💾 Spatie Laravel Settings Integration: Strictly powered by spatie/laravel-settings with type-safe setting classes and database migrations.
🛡️ Optional Shield Integration: Seamless permission resolution using bezhansalleh/filament-shield without hardcoding dependencies.
🚀 Artisan Generators: Easily generate tabs, sub-tabs, static pages, settings classes, and migrations using php artisan make:settings-tab, make:settings-sub-tab, and make:settings-page.
🔍 Automatic Discovery: Automatically discovers tabs and sub-tabs from your app/Filament/Settings/Tabs directory.
🔌 External Package Registration: Third-party packages can register custom settings tabs via Service Providers.

Installation

You can install the package via composer (spatie/laravel-settings will be automatically installed as a dependency):

composer require islamv/app-settings-plugin

Publish and run the Spatie Settings & Plugin migrations:

php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsServiceProvider"
php artisan vendor:publish --provider="Islamv\AppSettingsPlugin\AppSettingsServiceProvider"
php artisan migrate

Registration in Panel

use Islamv\AppSettingsPlugin\AppSettingsPlugin;

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

Configuration

The plugin configuration file config/app-settings.php allows you to customize navigation, locales, file upload disk, and discovery behavior:

return [
    'navigation' => [
        'label' => 'Settings',
        'icon'  => 'heroicon-o-cog-6-tooth',
        'group' => null,
        'sort'  => 100,
    ],

    'locales' => [
        'en' => ['label' => 'English', 'direction' => 'ltr'],
        'ar' => ['label' => 'Arabic',  'direction' => 'rtl'],
    ],

    'uploads' => [
        'disk'      => env('APP_SETTINGS_DISK', 'public'),
        'directory' => env('APP_SETTINGS_DIRECTORY', 'settings'),
    ],

    'discovery' => [
        'enabled'   => true,
        'path'      => null, // defaults to app/Filament/Settings/Tabs
        'namespace' => null, // defaults to App\Filament\Settings\Tabs
    ],
];

Usage & Tab Management

Fluent API Customization

In your PanelProvider:

AppSettingsPlugin::make()
    ->layout(\Islamv\AppSettingsPlugin\Enums\SettingsLayout::Sidebar) // Switch to sidebar layout instead of default tabs
    ->useShield(true) // Enable Filament Shield permission checks
    ->withoutDefaultTabs() // Disable built-in General, Social, Static Pages tabs
    ->removeTab('social-links') // Remove a specific tab
    ->locales([
        'en' => ['label' => 'English', 'direction' => 'ltr'],
        'ar' => ['label' => 'Arabic', 'direction' => 'rtl'],
        'fr' => ['label' => 'French', 'direction' => 'ltr'],
    ])
    ->tab(PaymentSettingsTab::make()->group('Finance')) // Grouping in sidebar layout
    ->subTab('static-pages', ContactUsSubTab::make()); // Register sub-tab under existing tab

Layout Options

The plugin provides two distinct layouts for the settings page:

Tabs Layout (tabs): The default layout. Displays top-level sections as horizontal tabs across the top of the page.
Sidebar Layout (sidebar): A secondary layout where top-level sections are displayed in a vertical navigation sidebar on the left, with the active section's form on the right.

Enabling the Sidebar Layout

You can change the layout via the plugin configuration in your Panel Provider:

AppSettingsPlugin::make()->layout(\Islamv\AppSettingsPlugin\Enums\SettingsLayout::Sidebar);

Grouping Tabs in Sidebar Layout

When using the sidebar layout, you can logically group tabs by assigning a group name.

// In a custom tab class
public function getGroup(): ?string
{
    return 'Account & Security';
}

// Or fluently
$plugin->tab(PaymentSettingsTab::make()->group('Finance'));

Artisan Scaffolding Generators

1. Generate a Main Tab

Creates a main Settings Tab along with a Spatie Settings class and database migration.

php artisan make:settings-tab Payment --sort=40 --icon=heroicon-o-credit-card

2. Generate a Sub-Tab

Creates a sub-tab nested under a parent tab.

php artisan make:settings-sub-tab Stripe --parent=payment --sort=10

3. Generate a Static Page

Creates a translatable static page sub-tab under the built-in static-pages main tab.

php artisan make:settings-page RefundPolicy --sort=40

Automatic Discovery Convention

When automatic discovery is enabled, tabs are automatically loaded based on folder structure:

app/Filament/Settings/Tabs/
├── PaymentSettingsTab.php            <-- Main Tab
└── Payment/
    ├── StripeSettingsSubTab.php      <-- Sub-Tab under 'payment'
    └── PaypalSettingsSubTab.php      <-- Sub-Tab under 'payment'

Shield & Authorization

When Shield integration is enabled (->useShield(true)), permission keys follow this convention:

Settings Page: page_settings
Main Tab: page_settings_{tab_key} (e.g. page_settings_general, page_settings_payment)
Sub-Tab: page_settings_{parent_key}_{subtab_key} (e.g. page_settings_static_pages_privacy_policy)

Third-Party Package Registration

External packages can register settings tabs in their ServiceProvider boot() method:

use Islamv\AppSettingsPlugin\Registry\SettingsRegistry;

public function boot(): void
{
    $registry = app(SettingsRegistry::class);
    $registry->register(MyPackageSettingsTab::make());
}

License

The MIT License (MIT). Please see License File for more information.

islamv / app-settings-plugin

Package info

Security

Statistics