Filament Sitemap Generator Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require muhammad-nawlo/filament-sitemap-generator
   

   Publish the config:

   php artisan vendor:publish --provider="MuhammadNawlo\FilamentSitemapGenerator\FilamentSitemapGeneratorServiceProvider" --tag="config"
   

2. Register Plugin Add to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \MuhammadNawlo\FilamentSitemapGenerator\FilamentSitemapGeneratorPlugin::make(),
           ]);
   }
   

3. First Use Case Configure a basic sitemap in config/filament-sitemap-generator.php:

   'sitemaps' => [
       'default' => [
           'url' => '/sitemap.xml',
           'items' => [
               \App\Sitemap\PostSitemap::class,
           ],
       ],
   ],
   

   Create a sitemap class (e.g., app/Sitemap/PostSitemap.php):

   use Spatie\Sitemap\Sitemap;
   use Spatie\Sitemap\Tags\Url;
   
   class PostSitemap extends Sitemap
   {
       public function index(): array
       {
           return \App\Models\Post::query()
               ->get()
               ->map(fn ($post) => Url::create($post->path)
                   ->setLastModificationDate($post->updated_at)
                   ->setChangeFrequency(Url::CHANGE_FREQUENCY_DAILY));
       }
   }
   

4. Access the Plugin Visit /admin/sitemaps in your Filament admin panel to generate and manage sitemaps.

Implementation Patterns

Core Workflows

1. Dynamic Sitemap Generation Use the plugin’s Filament UI to trigger sitemap generation via:

   // In a Filament action or controller
   $this->call(SitemapGenerator::class);
   

   Or via CLI:

   php artisan sitemap:generate
   

2. Sitemap Splitting Configure chunked sitemaps in config/filament-sitemap-generator.php:

   'sitemaps' => [
       'posts' => [
           'url' => '/sitemap-posts.xml',
           'items' => [\App\Sitemap\PostSitemap::class],
           'split' => [
               'enabled' => true,
               'chunk_size' => 500,
               'index_url' => '/sitemap-posts-index.xml',
           ],
       ],
   ],
   

3. Advanced Sitemap Features

   • News Sitemaps: Extend Sitemap and use NewsUrl:

     use Spatie\Sitemap\Tags\NewsUrl;
     
     public function index(): array
     {
         return NewsUrl::create('/news/1')
             ->setLastModificationDate(now())
             ->setPublicationDate(now()->subDays(1))
             ->setArticleEngagement([
                 'total_engagement' => 100,
                 'likes' => 50,
             ]);
     }
     

   • Image Sitemaps: Use ImageUrl:

     use Spatie\Sitemap\Tags\ImageUrl;
     
     public function index(): array
     {
         return ImageUrl::create('/post/1')
             ->addImage('/images/post-1.jpg', 500, 500, 'image/jpeg');
     }
     

   • Alternate Language Links: Use AlternateUrl:

     use Spatie\Sitemap\Tags\AlternateUrl;
     
     public function index(): array
     {
         return Url::create('/post/1')
             ->addAlternate(AlternateUrl::create('/es/post/1', 'es'));
     }
     

4. Search Engine Ping Automatically ping search engines after generation by configuring:

   'ping_search_engines' => true,
   

   in the config. Customize pings in the SitemapGenerator service.

5. Caching Leverage Laravel’s cache for performance:

   'cache' => [
       'enabled' => true,
       'ttl' => 60, // minutes
   ],
   

Integration Tips

1. Filament Resource Integration Attach sitemap generation to a Filament resource’s action:

   public static function getActions(): array
   {
       return [
           SitemapGenerateAction::make(),
       ];
   }
   

2. Event-Based Generation Trigger sitemap updates on model events (e.g., saved):

   // In PostObserver.php
   public function saved(Post $post)
   {
       event(new SitemapRegenerateEvent());
   }
   

3. Customizing the Filament UI Override the plugin’s views by publishing assets:

   php artisan vendor:publish --provider="MuhammadNawlo\FilamentSitemapGenerator\FilamentSitemapGeneratorServiceProvider" --tag="views"
   

   Then modify resources/views/vendor/filament-sitemap-generator/....

4. API-Driven Generation Expose an API endpoint for programmatic generation:

   Route::post('/api/sitemap/generate', function () {
       $generator = app(SitemapGenerator::class);
       return response()->json($generator->generate());
   });
   

Gotchas and Tips

Pitfalls

1. Compatibility Issues

   • Filament v3 vs. v4/5: The plugin uses getter overrides, but ensure your Filament version supports dynamic navigation labels. Test in a staging environment first.
   • Laravel Version: The underlying spatie/laravel-sitemap may have version constraints. Check the Spatie docs for compatibility.

2. Sitemap Indexing

   • If using split, ensure the index_url is correctly configured to avoid broken links. Test with:

     php artisan sitemap:generate --sitemap=posts
     

3. Caching Quirks

   • Clear cache manually if sitemaps aren’t updating:

     php artisan cache:clear
     php artisan sitemap:clear-cache
     

   • Cache TTL is in minutes, not seconds.

4. URL Generation

   • Absolute URLs are generated by default. Use setAbsoluteUrl(false) in Url::create() for relative paths if needed:

     Url::create('/post/1')->setAbsoluteUrl(false)
     

5. Search Engine Ping Failures

   • Pings may fail silently. Log pings for debugging:

     'ping_search_engines' => [
         'enabled' => true,
         'log_pings' => true, // Add this to config
     ],
     

Debugging Tips

1. Log Sitemap Contents Temporarily log the generated XML for validation:

   // In your Sitemap class
   public function toXml(): string
   {
       $xml = parent::toXml();
       Log::debug('Sitemap XML:', ['xml' => $xml]);
       return $xml;
   }
   

2. Validate XML Use an online validator (e.g., XML Validation) to check the generated sitemap.xml.

3. Check File Permissions Ensure the storage directory (storage/app/sitemaps) is writable:

   chmod -R 755 storage/app/sitemaps
   

4. Debug Splitting If splits aren’t working, verify the chunk_size and test with a small number (e.g., 10) to isolate issues.

Extension Points

1. Custom Sitemap Generators Extend the base SitemapGenerator class to add logic:

   class CustomSitemapGenerator extends \MuhammadNawlo\FilamentSitemapGenerator\SitemapGenerator
   {
       public function generate(): void
       {
           // Custom logic before/after generation
           parent::generate();
           $this->notifyAdmins();
       }
   }
   

   Bind it in AppServiceProvider:

   $this->app->bind(SitemapGenerator::class, CustomSitemapGenerator::class);
   

2. Dynamic Sitemap Configuration Load sitemap configurations from a database or API:

   // In a custom generator
   $configs = \App\Models\SitemapConfig::all()->toArray();
   $this->setSitemaps($configs);
   

3. Webhook Triggers Integrate