Filament Survey Laravel Package

Getting Started

Minimal Steps to First Use

1. Install Dependencies:

   composer require matt-daneshvar/laravel-survey:"dev-translatable" tapp/filament-survey:"^3.0"
   

   Add the custom repository to composer.json as per the README.

2. Run Migrations:

   php artisan vendor:publish --provider="MattDaneshvar\Survey\SurveyServiceProvider" --tag="migrations"
   php artisan migrate
   

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

   public function panel(Panel $panel): Panel {
       return $panel
           ->plugins([
               FilamentSurveyPlugin::make(),
               SpatieLaravelTranslatablePlugin::make(),
           ]);
   }
   

4. First Survey Creation:

   • Navigate to the Surveys resource in Filament.
   • Click "Create Survey" and use the relation manager to add sections/questions.
   • Publish the config (php artisan vendor:publish --tag="filament-survey-config") to enable Sections/Questions resources if needed.

First Use Case: Quick Feedback Survey

1. Create a Survey:

   • Title: "Customer Onboarding Feedback"
   • Description: "How was your experience setting up our product?"
   • Set language (e.g., en, es) if using translations.

2. Add Sections:

   • Use the relation manager to add a section like "Setup Process."

3. Add Questions:

   • Under the section, add a multiple-choice question:
     • Question: "How easy was the setup?"
     • Options: ["Very Easy", "Easy", "Neutral", "Difficult", "Very Difficult"]
     • Set required: true.

4. Publish and Test:

   • Use Laravel Survey’s frontend (or a custom form) to submit responses.
   • View results in the Entries resource.

Where to Look First

• Filament Resources:

  • /resources/surveys – Manage surveys.
  • /resources/entries – View/analyze responses (answers consolidated here).
  • (Optional) /resources/questions, /resources/sections – If published via config.

• Config File:

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

  • Toggle enable_question_resource and enable_section_resource to control visibility.

• Translations:

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

  • Customize labels for multilingual support.

Implementation Patterns

Core Workflows

1. Survey Creation Workflow

• Relation Manager Pattern: Surveys use Filament’s relation manager to nest sections/questions. This avoids the "multiple-page" issue in v2.x.

  // Example: Customizing the relation manager (via config)
  'survey_relation_managers' => [
      'sections' => [
          'label' => 'Sections',
          'relation' => 'sections',
          'subrelation' => 'questions',
      ],
  ],
  

• Drag-and-Drop Ordering: Leverage spatie/eloquent-sortable for reordering sections/questions via Filament’s sortable widgets.

2. Response Handling

• Entries Resource: Consolidates responses + answers into a single table. Use Filament’s table actions to:
  • Export entries to Excel (maatwebsite/excel).
  • Filter by survey, date, or user metadata.

  // Example: Customizing the Entries table columns
  EntriesResource::modifyTableColumns(function (Table $table) {
      $table
          ->columns([
              Tables\Columns\TextColumn::make('survey.title'),
              Tables\Columns\TextColumn::make('created_at')->dateTime(),
              // Custom column for answer data
              Tables\Columns\TextColumn::make('answers_data')->json(),
          ]);
  });
  

3. Translatable Surveys

• Field Translation: Use Filament’s SpatieLaravelTranslatablePlugin to manage translations for:
  • Survey titles/descriptions.
  • Question text/options.

  // Example: Adding a translatable field to a question
  use Filament\Forms\Components\SpatieTranslatableFields;
  
  TextInput::make('title')
      ->translatable()
      ->required(),
  

4. Bulk Operations

• Excel Import/Export: Use Filament’s import and export actions for surveys/entries.

  // Example: Adding an export button to the Surveys table
  SurveysResource::modifyTableBulkActions(function (Table $table) {
      $table->action(ExportAction::make());
  });
  

Integration Tips

1. Frontend Survey Forms

• Use Laravel Survey’s Blade views or a package like laravel-survey-frontend to render forms.
• Pass the survey ID to preload questions:

  {!! Survey::find($surveyId)->renderForm() !!}
  

2. Customizing Survey Logic

• Question Types: Extend Laravel Survey’s question types (e.g., add a rating type) by publishing the package’s views and overriding templates.
• Validation Rules: Add custom validation to questions via Filament’s form components:

  TextInput::make('question_text')
      ->rules(['required', 'max:255'])
      ->columnSpanFull(),
  

3. Analytics

• Filament Charts: Integrate with filament/spatie-laravel-charts to visualize response data:

  use Filament\Charts\Chart;
  
  Chart::make()
      ->title('Survey Responses Over Time')
      ->dataset('responses', [
          'data' => Entry::query()
              ->selectRaw('DATE(created_at) as date, COUNT(*) as count')
              ->groupBy('date')
              ->get(),
      ]),
  

4. Access Control

• Use Filament’s policies to restrict survey access:

  SurveysResource::configurePolicies([
      'viewAny' => [SurveyPolicy::class, 'viewAny'],
  ]);
  

• Example policy:

  public function viewAny(User $user) {
      return $user->hasRole(['admin', 'survey_manager']);
  }
  

5. Webhooks/Notifications

• Trigger actions on survey submission via Laravel events:

  // In EventServiceProvider
  protected $listen = [
      'MattDaneshvar\Survey\Events\SurveySubmitted' => [
          SurveySubmittedHandler::class,
      ],
  ];
  

• Send notifications via Filament’s notify() helper or a queue job.

Gotchas and Tips

Pitfalls

1. Schema Conflicts:

   • If your app already uses surveys, questions, or responses tables, migrations may fail. Run:

     php artisan schema:dump
     

     to compare schemas before migrating.

2. Translatable Fields Require Setup:

   • The dev-translatable fork of Laravel Survey adds translatable fields, but Filament’s translatable plugin must be installed (spatie/laravel-translatable). Missing this will cause errors when saving translated content.

3. Relation Manager Caching:

   • Filament’s relation manager can lag with large surveys. Optimize with:

     // In config/filament-survey.php
     'relation_manager_options' => [
         'sections' => [
             'loadRecords' => function () {
                 return Section::query()->where('survey_id', $this->record->id)->orderBy('sort_order');
             },
         ],
     ],
     

4. Excel Export Limitations:

   • The maatwebsite/excel dependency may conflict with other packages using the same namespace. Use:

     composer require maatwebsite/excel:^3.1
     

     to pin a specific version.

5. Sortable Fields Dependencies:

   • spatie/eloquent-sortable must be installed and migrations run for drag-and-drop to work. Check:

     php artisan vendor:publish --provider="Spatie\Sortable\SortableServiceProvider" --tag="sortable-migrations"
     php artisan migrate
     

Debugging Tips

1. Relation Manager Not Loading:

   • Clear Filament’s cache:

     php artisan filament:cache-clear
     

   • Check for missing relations in the surveys table (e.g., hasMany for sections).

2. **Translations Not S