Getting Started

Minimal Setup

Installation

composer require filafly/theme-core

Publish the package assets and config:

php artisan vendor:publish --provider="Filafly\ThemeCore\ThemeCoreServiceProvider" --tag="theme-core-config"
php artisan vendor:publish --provider="Filafly\ThemeCore\ThemeCoreServiceProvider" --tag="theme-core-assets"

Basic Configuration Update config/theme-core.php to define your theme name, assets paths, and Filament integration settings:

'theme' => [
    'name' => 'MyCustomTheme',
    'assets' => [
        'path' => resource_path('views/vendor/filafly-theme-core'),
    ],
],

First Use Case: Extending a Theme Create a custom theme class by extending Filafly\ThemeCore\Contracts\Theme:

namespace App\Themes;

use Filafly\ThemeCore\Contracts\Theme;

class MyTheme implements Theme
{
    public function getName(): string
    {
        return 'MyCustomTheme';
    }

    public function getAssets(): array
    {
        return [
            'css' => ['css/app.css'],
            'js' => ['js/app.js'],
        ];
    }
}

Register the Theme Bind your theme in AppServiceProvider:

public function register()
{
    $this->app->bind(
        \Filafly\ThemeCore\Contracts\Theme::class,
        \App\Themes\MyTheme::class
    );
}

Apply the Theme to Filament In your filament.php config:

'themes' => [
    'default' => env('FILAMENT_THEME', 'my-custom-theme'),
],

Implementation Patterns

Core Workflows

1. Theme Asset Management

Static Assets: Place CSS/JS in resources/views/vendor/filafly-theme-core/ (or custom path in config).
Dynamic Assets: Use Blade directives (@themeStyles, @themeScripts) to inject assets conditionally:
```
@themeStyles
    <link href="{{ asset('css/custom.css') }}" rel="stylesheet">
@endthemeStyles
```
Versioning: Leverage Laravel Mix/Vite to fingerprint assets for cache-busting.

2. Theme Customization

Override Default Views: Publish and modify Filament views in resources/views/vendor/filament/.
```
php artisan vendor:publish --tag="filament-views"
```

Partial Overrides: Use theme-core's partials system to replace sections (e.g., headers, footers):

// In your theme class
public function getPartials(): array
{
    return [
        'header' => 'filafly-theme-core::partials.header',
    ];
}

Dark Mode: Extend the DarkMode trait for toggle support:

use Filafly\ThemeCore\Traits\DarkMode;

class MyTheme implements Theme
{
    use DarkMode;
}

3. Filament Integration

Panel Configuration: Extend Filament’s Panel class to apply theme settings:

use Filafly\ThemeCore\Filament\ThemePanel;

class CustomPanel extends ThemePanel
{
    protected static string $theme = 'my-custom-theme';
}

Widget Customization: Override Filament widgets by publishing their views:
```
php artisan vendor:publish --tag="filament-widget-views"
```

Resource Styling: Scope CSS/JS to specific resources using Filament’s Resource classes:

use Filafly\ThemeCore\Traits\ResourceStyling;

class PostResource extends Resource
{
    use ResourceStyling;

    protected static string $themeResource = 'posts';
}

4. Localization & RTL Support

Language Switching: Use Filament’s localization with theme-specific assets:

// In your theme class
public function getAssetsForLocale(string $locale): array
{
    return [
        'css' => ["css/{$locale}.css"],
    ];
}

RTL: Enable in config and override direction-specific assets:

'rtl' => [
    'enabled' => true,
    'assets' => [
        'css' => ['css/rtl.css'],
    ],
],

5. Dynamic Theming

User-Based Themes: Bind themes dynamically in middleware:

public function handle(Request $request, Closure $next)
{
    $theme = auth()->user()->preferred_theme ?? config('theme-core.default');
    app()->bind(\Filafly\ThemeCore\Contracts\Theme::class, "App\Themes\\{$theme}Theme");

    return $next($request);
}

Theme Switcher: Build a Filament widget to toggle themes at runtime.

Integration Tips

With Filament v4/v5

v5 Compatibility: Use filafly/theme-core’s v5 config flag to enable v5-specific features (e.g., spa_mode).
Livewire Hooks: Extend Filament’s Livewire components by publishing their views and overriding methods in your theme class.

With Laravel Mix/Vite

Asset Compilation: Configure Mix/Vite to process theme assets:

// vite.config.js
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel({
            input: [
                'resources/js/filafly-theme-core/app.js',
                'resources/sass/filafly-theme-core/app.scss',
            ],
            refresh: true,
        }),
    ],
});

Public Path: Ensure public_path() in config/theme-core.php points to /public.

With Tailwind CSS

Customize Theme: Extend tailwind.config.js to include theme-specific colors:

module.exports = {
    theme: {
        extend: {
            colors: {
                primary: {
                    500: '#3b82f6', // Override with your theme's palette
                },
            },
        },
    },
};

Theme Variables: Use CSS variables in your theme’s SCSS:

:root {
    --primary-500: theme('colors.primary.500');
}

Gotchas and Tips

Pitfalls

Asset Loading Order
- Issue: Theme assets may load after Filament’s core assets, causing styles to override incorrectly.
- Fix: Use @stack directives to control load order:
```
@stack('meta.styles.pre')
@themeStyles
@stack('meta.styles')
```
Caching Conflicts
- Issue: Laravel/Filament cache may prevent theme changes from reflecting.
- Fix: Clear caches after publishing assets:
```
php artisan cache:clear
php artisan view:clear
php artisan filament:cache-reset
```
Namespace Collisions
- Issue: Custom theme classes may conflict with Filament’s autoloading.
- Fix: Use fully qualified class names or alias namespaces in composer.json:
```
"autoload": {
    "psr-4": {
        "App\\Themes\\": "app/Themes/"
    }
}
```

Dark Mode Toggle

Issue: Dark mode may not persist across page reloads.

Fix: Store the preference in a cookie or database:

// In your theme class
public function toggleDarkMode(): void
{
    $preference = request()->cookie('dark_mode') === 'true';
    session()->put('dark_mode', $preference);
    response()->cookie('dark_mode', $preference ? 'true' : 'false', 60 * 24 * 30);
}

Partial Overrides
- Issue: Overriding partials may break Filament’s blade components.
- Fix: Extend the original partial instead of replacing it:
```
@extends('filament::partials.header')
@section('header.extra')
    <div class="custom-header-content"></div>
@endsection
```

Debugging Tips

Asset Paths
- Verify paths in config/theme-core.php and resources/views/vendor/filafly-theme-core/.
- Use {{ asset('') }} in Blade to debug paths.
Theme Binding
- Check if your theme is bound correctly:
```
dd(app(\Filafly\ThemeCore\Contracts\Theme::
```

Theme Core Laravel Package