Filament Survey Laravel Package

Getting Started

1. Verify your Filament major version first. The plugin ships one major per Filament major (2.x, 3.x, 4.x branches/tags). If you're on Filament 3, you want tapp/filament-survey:^3.0; on Filament 4, install from the 4.x branch. Getting this wrong is the single most common install failure.

2. Install the forked survey engine — not the upstream package. This is the step people skip. The plugin depends on tappnetwork/laravel-survey on the dev-translatable branch (translatable + sortable fields). You must add a VCS repository and require the dev branch explicitly:

"require": {
    "matt-daneshvar/laravel-survey": "dev-translatable",
    "tapp/filament-survey": "^3.0"
},
"repositories": [
    { "type": "vcs", "url": "https://github.com/TappNetwork/laravel-survey" }
]

3. Publish migrations from the Survey provider — not the plugin. The plugin has no migrations of its own:

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

4. Register both plugins in your panel provider. The plugin's survey forms rely on Spatie Translatable, so install filament/spatie-laravel-translatable-plugin and register it with your locale list:

->plugins([
    FilamentSurveyPlugin::make(),
    SpatieLaravelTranslatablePlugin::make()->defaultLocales(['en', 'fr']),
])

5. First use case — the 10-minute smoke test. Open the panel: you should see Surveys, Entries, and Answers in the sidebar. Create a survey, then add a section and questions from the relation managers on the survey edit page (since v3.1.0 this is the whole authoring flow — no more hopping between pages). Then submit an entry programmatically from tinker so you can confirm the read path in the Entries resource:

$survey = \MattDaneshvar\Survey\Models\Survey::first();
$entry = $survey->entries()->create(['participant_id' => auth()->id()]);
$entry->answers()->create(['question_id' => $survey->questions()->first()->id, 'value' => 'Yes']);

Where to look first: vendor/tapp/filament-survey/src/Resources/ (the resource classes are the real documentation), config/filament-survey.php (the resources array controls what's registered), and the fork's src/Models/ for the actual schema and relationships.

Implementation Patterns

Authoring: survey → sections → questions, all in one screen. Sections are optional grouping; questions carry the type (text, radio, select, etc.), options, and validation rules. Because sorting is handled by spatie/eloquent-sortable, reordering questions in the UI persists an order column — treat that column as authoritative and never seed rows without it.

The plugin is the back office, not the participant experience. Nothing here renders a public survey form. Day-to-day, you build the participant-facing submission yourself against the Laravel Survey API and use the Filament resources to author content and review results. A typical controller:

$survey->entries()->create(['participant_id' => $user->id])
    ->answers()->createMany($validatedAnswers); // question_id => value

Expose Section and Question as standalone resources only if you need to. Publish the config and add them to the resources array:

// config/filament-survey.php
'resources' => [
    // \Tapp\FilamentSurvey\Resources\SurveyResource::class,
    // ...
    \Tapp\FilamentSurvey\Resources\SectionResource::class,
    \Tapp\FilamentSurvey\Resources\QuestionResource::class,
],

Leave them out for the cleaner v3.1+ flow (everything nested under the survey). Add them when non-technical users need to bulk-edit a question bank across surveys.

Override resources by subclassing, not forking. The config points at class strings, so your extension point is:

// config/filament-survey.php
'resources' => [
    \App\Filament\Resources\SurveyResource::class, // extends the vendor class, adds fields/actions
],

Then php artisan filament:clear-cached-components in any cached environment — Filament caches component class lists and will happily keep serving the vendor resource after you swap it.

Translations are per-locale, per-field, and easy to half-save. The translatable plugin switches the entire form to the active locale. If an editor fills in English, switches to French, adds one field and saves, only the French values in scope are written — check getLocale() before assuming a field was persisted. A practical guardrail is a relation-manager table column showing translation completeness.

Entries → Answers read path. Answers are consolidated under the Entries resource (v3.1+). For CSV/XLSX extracts, use the built-in export (maatwebsite/excel) — it's the intended reporting path, and hand-rolling Entry::with('answers.question') into a spreadsheet duplicates work you already paid for in dependencies.

Multi-tenancy / scoping. participant_id is the only ownership hook. If your panel is tenant-scoped, add a where() on the resource's getEloquentQuery() via your resource subclass, and restrict Entries visibility rather than assuming the plugin does it.

Gotchas and Tips

The dev-translatable dependency is the biggest operational risk. It's a moving branch, so composer update can silently change survey behaviour, and composer install isn't reproducible across machines. Pin it to a SHA:

"matt-daneshvar/laravel-survey": "dev-translatable#a1b2c3d4"

and mirror the repo into your own VCS so the branch can't disappear on you.

This package is archived. No more fixes upstream — plan on treating vendor/tapp/filament-survey as a vendored fork you own, or vendor-publish it. Do a composer show/lockfile audit before pinning your Filament version, because a Filament minor bump may leave you stuck with an unreachable patch.

Migrations live under a different provider. vendor:publish --tag="filament-survey-*" will not create tables. If you see Base table or view not found: surveys, you skipped step 3.

Excel is a hard dependency. maatwebsite/excel pulls PhpSpreadsheet. If you only ever read data in the panel, that's dead weight in every request's autoload graph — but you can't drop it without editing the plugin.

Model/table name collisions. The fork registers Survey, Section, Question, Entry, Answer. If your app already has (or plans) a surveys table, the published migration will collide. Decide before running migrations; retrofitting means a data-mapping exercise.

Deleting questions with existing answers. Check the fork's foreign keys — cascade vs. restrict changes your admin UX materially. In practice, soft-delete or deactivate questions rather than deleting them, and never reorder/delete while an entry is mid-submission.

Debugging checklist, in order: plugin registered after the translatable plugin → locales configured on the translatable plugin → config published and cached cleared (php artisan config:clear, then filament:clear-cached-components) → migrations from the correct provider → resources array actually includes the class names you expect. Nine out of ten "resource missing" reports are a stale Filament component cache or an empty resources key.

Locale fallout on seeders and factories. Anything you seed directly into the DB must write the translatable JSON shape ({"en": "...", "fr": "..."}), not a plain string — otherwise the resource shows blank fields and the form will overwrite your seed on first save.