Getting Started

Minimal Steps

Installation:
```
composer require jeffersongoncalves/filament-logo:^3.0
```
Ensure your project uses Filament v5.3+ (check composer.json or run composer show filament/filament).
Automatic Activation: The plugin registers itself via Filament’s plugin system. No manual configuration is required in config/filament.php—it works out of the box.
First Use Case: Open your Filament admin panel on a mobile device (or simulate mobile view in browser dev tools). Verify the Filament logo appears at the top of the panel under the PanelsRenderHook::TOPBAR_BEFORE hook.

Where to Look First

Plugin Source: src/FilamentLogoPlugin.php Focus on the getPluginActions() and register() methods to understand how the logo is injected.
Hook Documentation: Filament’s PanelsRenderHook for TOPBAR_BEFORE.
Blade Template: The logo is rendered via a Blade component. Override logic is in resources/views/components/filament-logo.blade.php (if you need customization).

Implementation Patterns

Usage Patterns

Zero-Config Integration:
- Install the package, and the logo appears automatically in mobile views. Ideal for rapid prototyping or MVP phases where branding is a secondary concern.
Custom Logo Paths (Advanced): If you need to replace the default logo, override the Blade component:
```
php artisan vendor:publish --tag="filament-logo-views"
```
Publish the views to resources/views/vendor/filament-logo/ and modify filament-logo.blade.php to use a custom image path:
```
<img src="{{ asset('custom-logo.svg') }}" alt="Filament Logo" class="h-8">
```

Conditional Logo Display: Extend the plugin to toggle visibility based on user roles or environments:

// app/Providers/FilamentLogoServiceProvider.php
public function boot()
{
    FilamentLogoPlugin::make()
        ->visible(fn () => auth()->user()->can('view-admin-panel'));
}

Desktop Logo Placement: While the plugin is mobile-focused, you can replicate its logic for desktop by creating a custom plugin:

use Filament\Panel;
use Filament\Support\Facades\FilamentView;

FilamentView::register('desktop-logo', fn () => view('custom.desktop-logo'));
Panel::make()->topbarItems([
    FilamentView::make('desktop-logo'),
]);

Workflows

Branding Sprint:
- Day 1: Install the package and test mobile logo visibility.
- Day 2: Customize the logo path if needed (publish views).
- Day 3: Extend for desktop or conditional logic if required.
Plugin Ecosystem Integration: Combine with other Filament plugins (e.g., spatie/laravel-filament-settings) to manage logo settings in a centralized admin panel.
CI/CD Pipeline: Add a test step to verify logo rendering in mobile view:
```
composer test -- --filter="LogoTest"
```

Integration Tips

Filament Plugin Manager: If using Filament’s plugin manager, ensure the package is listed in config/filament.php:
```
'plugins' => [
    \JeffersonGoncalves\FilamentLogo\FilamentLogoPlugin::make(),
],
```

Theme Overrides: Use Filament’s theme system to style the logo without modifying the plugin:

/* resources/css/filament/filament-logo.css */
.filament-logo img {
    filter: invert(1);
}

Multi-Panel Support: If your app uses multiple Filament panels, register the plugin for specific panels:

Panel::make('admin')
    ->plugins([
        \JeffersonGoncalves\FilamentLogo\FilamentLogoPlugin::make(),
    ]);

Gotchas and Tips

Pitfalls

Filament Version Mismatch:
- Error: Class 'Filament\Panel' not found or Method routes() does not exist.
- Fix: Ensure you’re using Filament v5.3+ for the ^3.0 plugin version. Downgrade the plugin or upgrade Filament if needed.
```
composer require filament/filament:^5.3
```
Logo Not Appearing:
- Cause: The plugin only renders on mobile devices. Test using Chrome DevTools (Ctrl+Shift+M to toggle device toolbar).
- Debug: Check if the PanelsRenderHook::TOPBAR_BEFORE hook is being overridden by another plugin. Inspect the rendered HTML for the logo’s Blade component.
CSS Conflicts:
- Issue: Logo styling clashes with existing Filament themes.
- Solution: Use Filament’s CSS isolation or target the logo specifically:
```
.filament-logo img {
    width: auto;
    height: 2rem;
}
```
Plugin Registration Failure:
- Error: Plugin already registered.
- Fix: Ensure the plugin is only registered once. If using a service provider, check for duplicate registrations in register() methods.

Debugging

View Rendering: To debug why the logo isn’t rendering, add a temporary Blade directive in filament-logo.blade.php:
```
@dump('Logo rendered')
<img src="{{ asset('filament/logo.svg') }}" alt="Filament Logo">
```
Check the browser console or Laravel logs for the dump output.
Hook Priority: If the logo appears in the wrong location, inspect Filament’s hook priorities. The plugin uses TOPBAR_BEFORE, which has a default priority of 100. Override it if needed:
```
FilamentLogoPlugin::make()->hookPriority(50);
```

Config Quirks

No Configuration File: The plugin has no config/filament-logo.php file. All settings are managed via the plugin class methods (e.g., visible(), hookPriority()).

Dynamic Logo Sources: To fetch the logo from a dynamic source (e.g., user uploads), override the Blade component and use a helper:

// app/Helpers/FilamentLogoHelper.php
function filamentLogoUrl(): string
{
    return auth()->user()->logo_url ?? asset('filament/logo.svg');
}

Then update the Blade template:

<img src="{{ filamentLogoUrl() }}" alt="Filament Logo">

Extension Points

Custom Hooks: Extend the plugin to support additional hooks (e.g., TOPBAR_AFTER for desktop):

public function getPluginActions(): array
{
    return [
        PanelsRenderHook::make('desktop-logo')
            ->view('custom.desktop-logo')
            ->hook('Panels.RenderHooks.Topbar.After'),
    ];
}

Logo Analytics: Track logo impressions by modifying the Blade component:

<img src="{{ asset('filament/logo.svg') }}" alt="Filament Logo" onload="trackEvent('filament_logo_loaded')"


3. **Localization**:
 Add alt text localization by publishing the views and extending the Blade template:
 ```blade
<img src="{{ asset('filament/logo.svg') }}" alt="{{ __('filament::logo.alt_text') }}">

Add the translation to resources/lang/en/filament.php:

return [
    'logo' => [
        'alt_text' => 'Admin Panel Logo',
    ],
];

Performance Tips

Asset Optimization: Ensure the logo is optimized (e.g., SVG or compressed PNG) to avoid render-blocking delays. Use Laravel Mix or Vite to process the asset:
```
// vite.config.js
export default defineConfig({
    assetsInclude: ['**/*.svg'],
});
```

Lazy Loading: For non-critical logos, defer loading:

<img src="{{ asset('filament/logo.svg') }}" alt="Filament Logo" loading="lazy">

Filament Logo Laravel Package