Reporter Laravel Package

Getting Started

Reporter is a lightweight exception inbox for Laravel Admin: exceptions are written to the database and browsed through an admin UI instead of digging through storage/logs/laravel.log or SSHing into production. Treat it as a day-to-day triage tool, not a replacement for Sentry/Telescope.

Minimal setup path:

composer require laravel-admin-ext/reporter
php artisan admin:import reporter
php artisan migrate

Then confirm the extension is enabled in config/admin.php:

'extensions' => [
    'reporter' => [
        'enable' => true,
    ],
],

Open the admin panel and look for the Reporter menu entry, commonly under /admin/reporter. If the menu or route is missing, check admin_menu, re-run the importer, and clear caches:

php artisan admin:import reporter
php artisan config:clear
php artisan route:clear

First practical use case: trigger a test exception in staging, confirm a row appears in the Reporter table and in the admin list, open the detail page, and verify you can see the exception class, message, file/line, stack trace, and request context. Once that works, wire it into your application’s exception reporting path so production 500s land there automatically.

Implementation Patterns

Wire reporting into Laravel’s exception handler. Reporter only sees exceptions that reach its reporting entry point. In older Laravel apps this usually means calling the package reporter from app/Exceptions/Handler.php::report() alongside parent::report($e). In newer apps, use the reportable()/withExceptions hook. Keep the call guarded:

try {
    // Call the package's reporter entry point here, per its README.
    // Example shape: Reporter::report($e);
} catch (\Throwable $reportingFailure) {
    logger()->error('Reporter failed to store exception', [
        'exception' => $reportingFailure,
    ]);
}

Do not let a reporting failure mask the original exception or break the response.

Filter noise before it hits the table. Use Laravel’s shouldReport()/$dontReport or an explicit status/type check so you store actionable failures rather than 404s, validation errors, 419s, and expected business exceptions. A useful default is: store 500-level errors and uncaught exceptions; skip client errors unless you are actively debugging them.

Adopt a daily triage workflow. Open Reporter, sort/filter by latest, review new exception classes, and work from the detail page: copy the file/line and stack trace into the codebase, reproduce locally with the same URL/input, fix, deploy, then confirm the exception stops appearing. If the team uses issue tracking, paste the Reporter detail URL into the ticket so others can inspect the same trace.

Enrich context deliberately. The most useful records include environment, release/commit, route/URL, authenticated user id, tenant id, request id, and sanitized request input. Add this context where you call the reporter or via middleware/log context. Avoid dumping full request bodies, authorization headers, cookies, passwords, tokens, and PII.

Control access and retention. Reporter exposes stack traces and request data; restrict it with admin auth and permissions. Add a scheduled pruning job for old records, for example delete rows older than 30–90 days, and index created_at plus any commonly filtered columns such as exception class or URL.

Use environment-specific enablement. Enable it in staging and production where the admin UI is the shared debugging surface; keep it off or low-noise in local development where you already have debug tooling. If you need a separate DB connection for reporting, configure that explicitly so reporting does not depend on the same failing connection as the application.

Gotchas and Tips

• Database failure recursion is real. If the app failed because the DB is unavailable, the reporter’s DB write can fail too. Always wrap reporting in try/catch, log the reporting failure to file, and consider a separate connection or async fallback.
• This is an old package. Last release was 2022, stars are modest, and Laravel Admin itself is legacy. Pin versions, test against your Laravel/PHP version, and avoid assuming current Laravel exception APIs are supported without checking the package’s handler integration.
• Stack traces and payloads can be large. Use LONGTEXT/TEXT appropriately, truncate huge traces or request bodies, and verify the detail page does not break on long records. Check column limits if records appear blank or truncated.
• No rows? Check the full path. Confirm the exception is not excluded by $dontReport/shouldReport(), confirm the reporter call is actually reached, confirm migrations ran, confirm DB permissions, and check storage/logs/laravel.log for reporter failures. Clear config/route caches after changing config/admin.php.
• Recursive or duplicate noise. Repeated exceptions can flood the table. Filter expected exceptions, consider hashing/aggregating by exception class + file + line + route if you add customization, and prune aggressively.
• Secrets leak easily. Stack traces often include environment values and request data. Redact headers, cookies, tokens, passwords, and PII before storage; restrict the admin route; keep APP_DEBUG=false in production.
• Missing menu or 404 in admin. Re-run php artisan admin:import reporter, check admin menu permissions, and clear caches. If the route exists but the menu does not, add/fix the menu entry rather than editing vendor files.
• Do not treat it as an audit log or uptime monitor. Reporter is for exception triage. Pair it with structured logs, Sentry/Telescope, and alerting for critical failures; use Reporter as the developer-friendly “what broke and where?” view.