Filament Help Requests Laravel Package

Getting Started

1. Install and scaffold:

   composer require joelseneque/filament-help-requests
   php artisan vendor:publish --tag="help-requests-migrations"
   php artisan vendor:publish --tag="help-requests-config"   # optional, recommended
   php artisan migrate
   npm run build
   

2. Register the plugin in your panel provider (app/Providers/Filament/AdminPanelProvider.php) alongside the other ->plugin(...) calls.
3. Look first at the published config (config/help-requests.php) — it controls the storage disk and storage.max_files (default 5), and is the single place to tune upload behaviour.
4. First use case: open the help widget on a panel page, click Browse / drop / paste a screenshot, drop a numbered pin on the broken area, write a note for that pin, add a second screenshot if needed, and submit. The note text lands in the request body and the annotated images are attached.

Implementation Patterns

• Widget placement: render the help widget via the panel's render hook (or a dashboard widget) rather than editing vendor views, so upgrades stay clean. Keep any custom theming in your own Blade partial.
• Screenshots are arrays now (v1.1+): screenshots and replyScreenshots are Livewire array properties bound to wire:model with multiple. Treat them as array<int, TemporaryUploadedFile> in validation (screenshots.*), not a single file.
• Annotation flow: pin coordinates and per-pin notes are composed client-side, drawn onto the image, and appended to the comment/reply text. If you need the raw pin data for your own integrations, hook into the submitted text or extend the widget — the package does not expose a structured pin model.
• Admin actions: the built-in Reply and Update status actions accept up to storage.max_files screenshots. Reuse these actions in your own resource tables/actions rather than reimplementing upload handling.
• My Requests accordion: one thread expands at a time; deep links coming from a notification open the relevant request automatically. If you add your own notification classes, include the same request identifier so the accordion can resolve and expand it.
• Outbound channels: each screenshot is included in emails, the GitHub issue body, and the admin detail view. If you customise any of these (mail templates, issue formatters), iterate the paths array — a single-image assumption will silently drop attachments.
• Testing: use Livewire::test(HelpWidget::class)->set('screenshots', [UploadedFile::fake()->image('a.png')]) and assert the stored paths array. Update any test that set the old singular properties.

Gotchas and Tips

• Breaking rename (v1.0 → v1.1): screenshot and replyScreenshot are now screenshots and replyScreenshots and are arrays. Any subclassed widget, custom action, or test referencing the old names will fail — grep your codebase for both strings before deploying.
• Migration is mandatory: add_screenshot_paths_to_help_requests_tables adds the paths column. Requests created pre-upgrade keep their single screenshot; don't assume the new column is populated for historical rows — normalise old single-path records when reading.
• Config drift: if you published the config previously, storage.max_files will not exist in your copy. Add it explicitly, otherwise you'll silently fall back to the default of 5 and wonder why the key "isn't working".
• Rebuild assets and clear caches: the pin/annotation UI is front-end code. Skipping npm run build or php artisan optimize:clear produces stale JS and cached config/views — the most common "the new feature doesn't appear" report.
• Storage disk & permissions: confirm the configured disk is writable and public (or served via a signed URL route); annotated images are written server-side after client-side drawing, so a misconfigured disk fails at submit, not at upload.
• Validation: enforce storage.max_files on the server too (max: on the array, plus per-file image/mimes/max: size rules). Client-side limits are bypassable.
• Extension points: prefer publishing config and overriding views over forking the widget class; the Livewire property names are internal API and just changed once already.
• Debugging uploads: check livewire.temporary_file_upload limits and PHP upload_max_filesize / post_max_size — multi-image submissions hit these faster than the package's own max_files cap.