Filament Survey Laravel Package

## Getting Started

### Minimal Setup
1. **Install the Package**
   ```bash
   composer require tapp/filament-survey

Ensure compatibility with Filament 3.2+ and Laravel 12. Required dependencies (matt-daneshvar/laravel-survey, maatwebsite/excel, spatie/eloquent-sortable) must also be installed.

2. Publish Config & Migrations

   php artisan vendor:publish --provider="Tapp\FilamentSurvey\FilamentSurveyServiceProvider"
   php artisan migrate
   

   Note: Laravel 12 users may need to adjust config/database.php for migration table naming conventions.

3. Register the Plugin Update app/Providers/Filament/AdminPanelProvider.php for Filament 3.2+:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \Tapp\FilamentSurvey\FilamentSurveyPlugin::make(),
           ])
           ->discoverResources(
               in_array($this->app->environment('local'), true),
               app_path('Filament/Survey/')
           );
   }
   

4. First Use Case: Create a Survey

   • Navigate to Filament Dashboard > Surveys (auto-registered).
   • Use the updated Filament 3.2 UI to create surveys with:
     • Drag-and-drop question reordering (via spatie/eloquent-sortable).
     • Native support for Laravel 12’s improved Blade components in survey templates.

Implementation Patterns

Core Workflows

1. Survey Creation & Management

   • Filament 3.2 Resource Updates: Leverage new features like:
     • Action Groups for bulk survey operations.
     • Improved Table Filters (e.g., filter surveys by created_at range).
   • Translatable Fields: Enhanced multi-language support with Laravel 12’s translatable trait optimizations.

2. Question Types & Logic

   • New Question Type Hooks: Extend question types using Filament 3.2’s resource macros:

     SurveyQuestionResource::macro('customField', function (callable $callback) {
         return $callback($this);
     });
     

   • Conditional Logic: Updated UI for branching logic with Filament 3.2’s livewire-based form components.

3. Response Handling

   • Excel Export: Optimized for Laravel 12’s spatie/laravel-excel v3.x:

     use Tapp\FilamentSurvey\Exports\SurveyResponseExport;
     
     SurveyResponseExport::make()
         ->withHeadings(['Question', 'Response', 'Submitted At'])
         ->chunk(1000); // Leverage Laravel 12’s chunked exports
     

   • Analytics: Integrate with Laravel 12’s query caching for faster response filtering.

4. Integration with Filament 3.2

   • Embed Surveys in Pages:

     use Tapp\FilamentSurvey\Widgets\SurveyWidget;
     
     SurveyWidget::make()
         ->survey($survey)
         ->submitButtonText('Submit Feedback')
         ->livewire(); // Explicitly use Filament 3.2’s Livewire components
     

   • Dynamic Survey Selection:

     SurveyWidget::make()
         ->survey(fn () => Survey::where('is_active', true)->first())
         ->canSeeSurvey(fn (User $user) => $user->can('view_active_surveys'));
     

5. Localization

   • Laravel 12 Translation Improvements:
     • Use lang:load for dynamic survey translations:

       Survey::find($id)->loadTranslations(['title', 'description']);
       

     • Example translation structure (updated for Laravel 12):

       {
         "surveys.attributes.title": {
           "en": "Customer Satisfaction",
           "es": "Satisfacción del Cliente"
         }
       }
       

Advanced Patterns

1. Custom Question Types (Filament 3.2) Register custom question types using Filament’s resource registration:

   // app/Providers/FilamentSurveyServiceProvider.php
   public function boot()
   {
       FilamentSurvey::registerQuestionType(
           \App\Models\CustomQuestion::class,
           \App\Filament\Resources\CustomQuestionResource::class,
           alignment: 'end' // New Filament 3.2 alignment option
       );
   }
   

2. Webhook Triggers with Laravel 12 Use Laravel’s event dispatching with improved type safety:

   use Tapp\FilamentSurvey\Events\SurveySubmitted;
   
   SurveySubmitted::listen(function (SurveySubmitted $event) {
       Notification::route('mail', $event->response->email)
                   ->notify(new SurveySubmittedNotification($event->survey));
   });
   

3. Bulk Actions (Filament 3.2)

   • Soft Deletes: Enable for surveys/responses:

     Survey::enableSoftDeletes();
     

   • Bulk Restore:

     use Filament\Tables\Actions\BulkAction;
     
     BulkAction::make('restore')
         ->action(function (Collection $records) {
             foreach ($records as $record) {
                 $record->restore();
             }
         }),
     

Gotchas and Tips

Pitfalls

1. Filament 3.2 Migration Issues

   • Symfony 6.4 Dependencies: Ensure symfony/ux-live-component and filament/support are v1.0+.
   • Fix: Run:

     composer require filament/support:^1.0 filament/forms:^1.0
     

2. Laravel 12 Model Binding

   • Route Model Binding: Surveys/responses now use Laravel 12’s improved binding:

     Route::get('/surveys/{survey:model}', [SurveyController::class, 'show']);
     

   • Fix: Update routes if using custom binding logic.

3. Translatable Field Caching (Laravel 12)

   • Cache Tags: Use Cache::tags() for translated survey fields:

     Cache::tags(['survey-translations'])->put("survey:{$id}:translations", $translations);
     

   • Clear Cache:

     php artisan cache:clear --tags=survey-translations
     

4. Excel Export Limits (Laravel 12)

   • Chunked Exports: Adjust spatie/laravel-excel config for large datasets:

     'exports' => [
         'chunk_size' => 2000, // Default: 1000 (Laravel 12 optimized)
     ],
     

5. Filament 3.2 Plugin Isolation

   • Resource Discovery: If auto-registered resources conflict, explicitly disable:

     FilamentSurveyPlugin::make()
         ->disableResources(['Surveys', 'Questions'])
         ->registerResourcesManually();
     

Debugging Tips

1. Log Survey Events (Laravel 12) Use Laravel’s structured logging:

   event(new SurveySubmitted($response))->log();
   

   • View logs with:

     tail -f storage/logs/laravel.log | grep "survey:"
     

2. Validate Filament 3.2 Components

   • Livewire Debugging: Check for component conflicts:

     php artisan livewire:discover
     

   • Resource Validation: Ensure custom resources extend Filament\Resources\Resource (v3.2).

3. Database Seeding (Laravel 12) Use the updated seeder with Laravel 12’s database testing:

   php artisan db:seed --class=FilamentSurveySeeder --force
   

   • Test Database: Configure in .env:

     DB_CONNECTION=testing
     

Extension Points

1. Customize Survey UI (Filament 3.2)

   • Override Blade Components:

     php artisan vendor:publish --tag="filament-survey-views"
     

   • Update resources/views/filament-survey/ for Filament 3.2’s new Blade directives (e.g., @filamentTables).

2. Add Survey Metadata (Laravel 12) Extend the Survey model with Laravel 12’s attributes:

   // app/Models/Survey.php
   use HasMany;
   use Spatie\MediaLibrary\HasMedia;
   
   protected $casts = [
       'is_published' => 'boolean',
       'publish_at' => 'datetime',
   ];
   

3. **API Endpoints (Laravel 12