Filament Bug Reports Laravel Package

Getting Started

This is a Filament panel plugin that turns in-app user feedback into GitHub issues and gives you a triage board for them. v1.0.0 is the first tagged release, so treat it as a young package: read the (now extracted) README end-to-end before installing, since it is the only real source of truth for config keys.

Minimal path:

1. composer require cereal-killer-97/filament-bug-reports (verify the exact vendor name in the README — it was only just split out of the source repo).
2. Publish and run migrations: php artisan vendor:publish --tag="filament-bug-reports-migrations" then php artisan migrate. The resource needs its own table; nothing is auto-created for you.
3. Publish the config: php artisan vendor:publish --tag="filament-bug-reports-config". Set your GitHub owner/repo, token, and label mapping here before touching anything else.
4. Register the plugin on the panel(s) you want the UI in:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(BugReportsPlugin::make());
}

5. Create a GitHub personal access token with issues:write (and issues:read if you want status to sync back) and put it in config/filament-bug-reports.php via .env.

First use case: install it on an internal/staging panel, submit one bug report yourself, and confirm an issue actually lands in GitHub with the priority label attached. Do that before wiring it into anything user-facing — the failure mode (a silent 401 from GitHub) is not obvious from the Filament UI.

Where to look first in the source: the plugin class (for registered resources/widgets) and the config file. That tells you the whole surface area in about five minutes.

Implementation Patterns

Report form → GitHub issue as the primary flow. The core loop is: Filament form collects title/description/priority → a queued or inline HTTP call creates the issue → the local record stores the issue number/URL for later sync. Keep the GitHub call off the request cycle if you expect any volume; a slow or rate-limited GitHub API should not hang a user's form submission.

Priority as a first-class triage axis. v1.0.0 adds bug priority, which pairs with row grouping on the resource table. The natural pattern is to map priority to GitHub labels (e.g. priority:high) in config and then group the Filament table by that column, so the panel view and the GitHub view agree. Define the enum/options in one place and reuse it in both the form and the table filter.

Triage stats widget. The new stats overview is meant to sit at the top of the resource/list page. Use it as an at-a-glance count by status/priority. If your team is small, consider scoping it to ->pollingInterval() or leaving it static — an auto-refreshing stats widget on every page load will burn GitHub API quota fast.

Pairing with a not-found page. The v1.0.0 not-found page means deep links to a deleted or inaccessible report degrade gracefully. Worth keeping if you ever link reports from Slack or PRs.

Multi-panel / role gating. The plugin is panel-scoped. A common pattern is to register it only on an admin panel, or to canAccess() the resource by role, while exposing a lightweight "report a bug" action in the user-facing panel that writes to the same table. Since the report form is just a Filament resource, you can also mount it as a modal action rather than a full page.

Integration tips:

• Wrap the GitHub client behind an interface in your app and bind it, so you can fake it in tests. Testing against the real API is painful and rate-limited.
• Prefer a queued job with retry/backoff for issue creation; store the report locally first, then sync. This gives you a queue of unsent reports rather than lost ones.
• Use GitHub labels as the contract between the package and your workflow — labels are far easier to re-map later than database columns.

Gotchas and Tips

• v1.0.0 is a fresh tag on a young package. No prior assessment exists, so there is no migration history to lean on. Pin the version in composer.json and read the changelog on each bump — expect breaking changes in the 1.x line.
• The README was only just extracted from the source (PR #6). Docs and code may still drift. When something doesn't match, trust the source over the docs.
• Token scopes are the classic silent failure. A token without issues:write yields a 403/404 that surfaces as a generic error in the Filament notification. Log the GitHub response body in local and check storage/logs/laravel.log first when reports "don't appear".
• Rate limits. The stats widget plus row grouping plus any polling can stack up API calls quickly. If you hit 403s with a rate-limit message, cache GitHub responses (a few minutes is usually enough) or drop the stats widget from non-admin panels.
• Migrations need publishing explicitly. Unlike some Filament plugins, don't assume php artisan migrate will pick up the table — run the publish step first, or the resource page 500s on a missing table.
• Config quirks around owner/repo. These are usually flat config values rather than per-panel. If you run multiple Filament panels pointing at different repos, you'll need to override config at runtime or wrap the plugin rather than relying on defaults.
• Extension points worth knowing: the plugin class (to swap resources/widgets), the config (label and priority mapping), and the resource's table/form schema if you need extra columns. If the package doesn't expose a client binding you can override, subclass the resource or decorate the service rather than forking.
• Grouping + stats interaction: if you group by priority, confirm the stats widget counts across all groups, not just the current one — that's an easy source of "the numbers look wrong" bug reports about your bug reporter.
• Not-found page is new but shallow. Test it by hard-deleting a report record in a dev DB and hitting the URL; if it throws instead of rendering, that's a 1.0.1 candidate rather than something you can configure around.