Filament Browser Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tomatophp/filament-browser
   

   Publish the package assets and config:

   php artisan vendor:publish --provider="TomatoPHP\FilamentBrowser\FilamentBrowserServiceProvider"
   

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

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->id('admin')
           ->plugins([
               \TomatoPHP\FilamentBrowser\FilamentBrowserPlugin::make(),
           ]);
   }
   

3. First Use Case: Access the browser via the Filament admin panel (default path: /admin/browser). Navigate to your project’s root directory (e.g., /storage/app or /public) to browse, edit, or manage files.

Key Features to Explore Immediately

• File Browser: Navigate directories, view files, and inspect metadata (size, permissions, modified dates).
• Code Editor: Edit PHP, JS, CSS, or Markdown files directly in the browser (powered by Monaco Editor).
• File Operations: Create, rename, delete, and upload files/folders.
• Search: Quickly locate files using the search bar.

Implementation Patterns

Workflows

1. Server Configuration Management

• Use Case: Modify config/filament-browser.php to restrict access to sensitive directories (e.g., storage/logs, bootstrap/cache).

  'disallowed_directories' => [
      'storage/logs',
      'bootstrap/cache',
  ],
  

• Pattern: Whitelist allowed directories for super-admins:

  'allowed_directories' => [
      'storage/app',
      'public',
  ],
  

2. Integrating with Deployment

• Use Case: Use the browser to manually edit .env files or deployment scripts before running php artisan deploy.
• Pattern: Combine with Laravel Forge/Envoyer hooks for pre-deployment edits.

3. Debugging Files

• Use Case: Inspect and edit Blade templates, config files, or logs without SSH.
• Pattern: Bookmark critical directories (e.g., resources/views) in the browser for quick access.

4. Media Asset Management

• Use Case: Upload and manage media files (e.g., images, PDFs) directly via the browser.
• Pattern: Use the "Upload" button to add files to storage/app/public and symlink them to public/storage.

5. Collaboration

• Use Case: Share the browser with junior devs for quick file edits (e.g., fixing CSS or JS issues).
• Pattern: Grant temporary Filament admin access via spatie/laravel-permission and revoke afterward.

Integration Tips

• Custom File Types: Extend the package to support custom file icons or actions (e.g., for .env files):

  FilamentBrowser::registerFileType('env', '🌍', function ($file) {
      return view('filament-browser::custom.env-actions', ['file' => $file]);
  });
  

• Event Listeners: Listen for file changes to trigger notifications or backups:

  FilamentBrowser::listen('file.updated', function ($file) {
      Log::info("File updated: {$file->path()}");
  });
  

• Monaco Editor Extensions: Add language support or themes by extending the editor config:

  // resources/js/filament-browser.js
  monaco.editor.defineTheme('dark-plus', { ... });
  

Gotchas and Tips

Pitfalls

1. Security Risks:

   • Issue: Exposing the browser to non-super-admins can lead to accidental or malicious file deletions.
   • Fix: Use Filament’s built-in role/gate policies to restrict access:

     Gate::define('access-filament-browser', function ($user) {
         return $user->isSuperAdmin();
     });
     

2. Performance:

   • Issue: Large directories (e.g., storage/app/public with thousands of files) may lag.
   • Fix: Limit directory depth or use Laravel’s Filesystem::allFiles() with pagination.

3. File Permissions:

   • Issue: The browser may fail to read/write files due to incorrect permissions (e.g., storage/ owned by www-data).
   • Fix: Ensure your Laravel user has proper permissions:

     chown -R www-data:www-data storage/
     chmod -R 775 storage/
     

4. Editor Conflicts:

   • Issue: Monaco Editor may conflict with other Filament plugins using the same editor.
   • Fix: Isolate the editor instance or use a unique namespace.

Debugging

• Logs: Enable debug mode in config/filament-browser.php:

  'debug' => env('FILAMENT_BROWSER_DEBUG', false),
  

  Check storage/logs/filament-browser.log for errors.

• Common Errors:

  • 403 Forbidden: Verify disallowed_directories and Filament permissions.
  • Blank Editor: Clear Filament cache:

    php artisan filament:cache-reset
    

  • File Not Found: Ensure paths in allowed_directories are absolute (e.g., /var/www/html/storage/app).

Tips

1. Keyboard Shortcuts: Use Ctrl+P for search, Ctrl+N to create a new file, and F2 to rename files.

2. Markdown Preview: Enable live preview for Markdown files by adding this to your filament-browser.js:

   document.addEventListener('filament-browser-ready', () => {
       const preview = document.getElementById('markdown-preview');
       if (preview) preview.style.display = 'block';
   });
   

3. Backup Integration: Automate backups of edited files using Laravel Scheduler:

   // app/Console/Kernel.php
   $schedule->command('filament-browser:backup')->daily();
   

4. Custom Actions: Add a "Download" button for files:

   FilamentBrowser::registerFileAction('download', '📥 Download', function ($file) {
       return redirect()->to($file->path());
   });
   

5. Multi-Tenancy: For SaaS apps, scope the browser to the current tenant’s storage:

   FilamentBrowser::scopeDirectories(function () {
       return [tenantStoragePath()];
   });