Filament Notes Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require tomatophp/filament-notes
   

   Publish the migration and config:

   php artisan vendor:publish --provider="TomatoPHP\FilamentNotes\FilamentNotesServiceProvider" --tag="filament-notes:migrations"
   php artisan vendor:publish --provider="TomatoPHP\FilamentNotes\FilamentNotesServiceProvider" --tag="filament-notes:config"
   

   Run migrations:

   php artisan migrate
   

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

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->resources([
               // ... other resources
               \TomatoPHP\FilamentNotes\Resources\NoteResource::class,
           ]);
   }
   

3. First Use Case Access /admin/resources/notes to create your first note. Use the Notes Widget (drag-and-drop) to pin it to your dashboard.

Implementation Patterns

Core Workflows

1. Note Creation & Management

   • Use the NoteResource to CRUD notes via Filament’s UI.
   • Leverage groups (group_id field) to categorize notes (e.g., "Dev Tasks," "Client Notes").
   • Set is_public to true for team-wide visibility (requires proper Filament permissions).

2. Styling Notes

   • Customize appearance via the Style tab in the note editor:

     // Override defaults in config/filament-notes.php:
     'default_background' => '#f0f0f0',
     'default_font_color' => '#333',
     'default_border_color' => '#ddd',
     

   • Use predefined styles (e.g., "Important," "Warning") via the UI dropdown.

3. Dashboard Integration

   • Add the Notes Widget to your dashboard:

     // In a Filament widget class:
     public static function canAccess(): bool
     {
         return true; // Or use Filament's auth gates
     }
     
     public function getWidgetData(): array
     {
         return [
             'notes' => \TomatoPHP\FilamentNotes\Models\Note::query()
                 ->where('is_pinned', true)
                 ->limit(5)
                 ->get(),
         ];
     }
     

   • Configure widget limits in config/filament-notes.php:

     'widget_limit' => 5, // Max pinned notes shown
     

4. Programmatic Access

   • Fetch notes in Laravel:

     use TomatoPHP\FilamentNotes\Models\Note;
     
     $notes = Note::where('group_id', 1)->get();
     

   • Create notes via API or console:

     Note::create([
         'title' => 'API Reminder',
         'content' => 'Check rate limits',
         'group_id' => 2,
         'is_pinned' => true,
         'background_color' => '#fff2cc', // "Warning" style
     ]);
     

5. Permissions

   • Restrict access via Filament’s Policies:

     // app/Policies/NotePolicy.php
     public function viewAny(User $user): bool
     {
         return $user->can('view notes'); // Custom gate
     }
     

Gotchas and Tips

Common Pitfalls

1. SQLite3 Dependency

   • Issue: Icons fail to load if SQLite3 PHP extension is missing.
   • Fix: Install via:

     # Ubuntu/Debian
     sudo apt-get install php-sqlite3
     # macOS (Homebrew)
     brew install php
     

   • Workaround: Use a fallback icon path in config/filament-notes.php:

     'icon_fallback_path' => 'path/to/local/icon.png',
     

2. Widget Caching

   • Issue: Notes widget may not update immediately due to Filament’s caching.
   • Fix: Clear Filament’s cache:

     php artisan filament:cache:clear
     

   • Tip: Use is_pinned + updated_at to force refreshes:

     ->where('updated_at', '>', now()->subMinutes(5))
     

3. Style Inheritance

   • Issue: Custom styles override defaults globally.
   • Fix: Scope styles to specific notes via style_id or inline overrides:

     'background_color' => '#ffeb3b', // Overrides default
     'font_color' => '#888',
     

4. Group Management

   • Issue: Orphaned groups after note deletion.
   • Fix: Soft-delete groups or use a hasNotes() check:

     // In a policy or query:
     ->whereHas('notes')
     

5. Permission Granularity

   • Issue: Public notes may expose sensitive data.
   • Fix: Combine is_public with Filament’s Resource Policies:

     public function edit(User $user, Note $note): bool
     {
         return $user->can('edit notes') || ($note->is_public && $user->can('view public notes'));
     }
     

Debugging Tips

• Log Note Queries: Enable Laravel’s query logging in .env:

  DB_LOG_QUERIES=true
  

• Check Filament Events: Listen for note updates:

  // In a service provider:
  event(new \TomatoPHP\FilamentNotes\Events\NoteUpdated($note));
  

• Inspect Widget Data: Dump widget data in a temporary route:

  Route::get('/debug-notes', function () {
      dd(\TomatoPHP\FilamentNotes\Widgets\NotesWidget::getWidgetData());
  });
  

Extension Points

1. Custom Note Fields

   • Extend the Note model:

     // app/Models/Note.php
     public function castAttributes(): array
     {
         return array_merge(parent::castAttributes(), [
             'priority' => 'integer',
         ]);
     }
     

   • Add to the resource’s form/table:

     // In NoteResource.php
     public static function form(Form $form): Form
     {
         return $form->schema([
             // ... existing fields
             Select::make('priority')
                 ->options([1 => 'Low', 2 => 'Medium', 3 => 'High']),
         ]);
     }
     

2. Dynamic Styling

   • Override styles via a NoteObserver:

     // app/Observers/NoteObserver.php
     public function saved(Note $note)
     {
         if ($note->priority === 3) {
             $note->update(['background_color' => '#ffcccb']);
         }
     }
     

   • Register in NoteServiceProvider:

     Note::observe(NoteObserver::class);
     

3. API Endpoints

   • Expose notes via Filament’s API:

     // routes/api.php
     Route::get('/notes', [\TomatoPHP\FilamentNotes\Http\Controllers\NoteController::class, 'index']);
     

   • Filter by user/group:

     return Note::where('group_id', request('group_id'))->get();
     

4. Webhook Triggers

   • Dispatch events for external integrations:

     // In NoteObserver.php
     public function created(Note $note)
     {
         event(new \TomatoPHP\FilamentNotes\Events\NoteCreated($note));
     }
     

   • Listen in another service:

     Event::listen(\TomatoPHP\FilamentNotes\Events\NoteCreated::class, function ($event) {
         // Send Slack notification, etc.
     });
     

5. Localization

   • Translate note labels via Filament’s localization:

     // lang/en/filament-notes.php
     return [
         'resources' => [
             'note' => [
                 'singular' => 'Memo',
                 'plural' => 'Memos',
             ],
         ],
     ];