README

Exception Viewer

A simple and beautiful exception viewer for Filament Panels. The plugin records every exception your app throws and lets you browse, inspect and prune them from inside the panel.

Table of Contents

Installation
Recording Control
- Stop and Start Recording
- Conditional Recording
Configuration Options
Custom Exception Model
Translations
Testing
Version Support
Changelog
Contributing
Security Vulnerabilities
Credits
License

Installation

Install the package with Composer:

composer require bezhansalleh/filament-exceptions

Publish and run the migration:

php artisan exceptions:install

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            \BezhanSalleh\FilamentExceptions\FilamentExceptionsPlugin::make()
        ]);
}

That's it. The package hooks into Laravel's exception handler and starts recording exceptions right away.

Important

The plugin follows Filament's theming rules. Create a custom theme if you haven't already, then add the following line to your theme.css file:

@source '../../../../vendor/bezhansalleh/filament-exceptions/resources/views/**/*.blade.php';

Then build your theme:

npm run build

Recording Control

The plugin records exceptions by default. Control that behavior from the boot() method of your AppServiceProvider.

Stop and Start Recording

use BezhanSalleh\FilamentExceptions\FilamentExceptions;

public function boot(): void
{
    // Stop recording exceptions
    FilamentExceptions::stopRecording();

    // Resume recording
    FilamentExceptions::startRecording();

    // Check whether recording is active
    FilamentExceptions::isRecording();
}

Conditional Recording

Call recordUsing() to decide, per exception, whether the plugin records it:

use BezhanSalleh\FilamentExceptions\FilamentExceptions;

public function boot(): void
{
    // Record only in production
    FilamentExceptions::recordUsing(fn () => app()->isProduction());

    // Skip specific exception types
    FilamentExceptions::recordUsing(function (Throwable $e) {
        return ! $e instanceof \Illuminate\Validation\ValidationException
            && ! $e instanceof \Illuminate\Auth\AuthenticationException;
    });

    // Combine several conditions
    FilamentExceptions::recordUsing(function (Throwable $e) {
        if (! app()->isProduction()) {
            return false;
        }

        // Skip 4xx HTTP exceptions
        if ($e instanceof \Symfony\Component\HttpKernel\Exception\HttpException
            && $e->getStatusCode() < 500) {
            return false;
        }

        return true;
    });
}

Configuration Options

Chain any of the following methods onto the plugin when you register it.

Navigation

FilamentExceptionsPlugin::make()
    ->navigationBadge(bool | Closure $condition = true)
    ->navigationBadgeColor(string | array | Closure $color)
    ->navigationGroup(string | Closure | null $group)
    ->navigationParentItem(string | Closure | null $item)
    ->navigationIcon(string | Closure | null $icon)
    ->activeNavigationIcon(string | Closure | null $icon)
    ->navigationLabel(string | Closure | null $label)
    ->navigationSort(int | Closure | null $sort)
    ->registerNavigation(bool | Closure $shouldRegisterNavigation)
    ->subNavigationPosition(SubNavigationPosition | Closure $position)

Labels and Search

FilamentExceptionsPlugin::make()
    ->modelLabel(string | Closure | null $label)
    ->pluralModelLabel(string | Closure | null $label)
    ->titleCaseModelLabel(bool | Closure $condition = true)
    ->globallySearchable(bool | Closure $condition = true)

Mass Pruning

FilamentExceptionsPlugin::make()
    ->modelPruneInterval(CarbonInterface $interval)

Note

Pruning runs through Laravel's scheduler, so make sure you have it running.

Tenancy

FilamentExceptionsPlugin::make()
    ->scopeToTenant(bool | Closure $condition = true)
    ->tenantOwnershipRelationshipName(string | Closure | null $ownershipRelationshipName)
    ->tenantRelationshipName(string | Closure | null $relationshipName)

General

FilamentExceptionsPlugin::make()
    ->cluster(string | Closure | null $cluster)
    ->slug(string | Closure | null $slug)

A combined example:

return $panel
    ->plugins([
        FilamentExceptionsPlugin::make()
            ->navigationLabel('Error Logs')
            ->navigationIcon('heroicon-o-bug-ant')
            ->navigationBadge()
            ->navigationGroup('System')
            ->modelPruneInterval(now()->subDays(7))
    ]);

Custom Exception Model

Extend the base model:

<?php

namespace App\Models;

use BezhanSalleh\FilamentExceptions\Models\Exception as BaseException;

class MyCustomException extends BaseException
{
    ...
}

use App\Models\MyCustomException;
use BezhanSalleh\FilamentExceptions\FilamentExceptions;
...
   public function boot()
   {
       FilamentExceptions::model(MyCustomException::class);
   }
...

Translations

Publish the translations:

php artisan vendor:publish --tag=filament-exceptions-translations

Testing

composer test

Version Support

Only the latest major plugin line receives active development. Older lines stay installable for legacy projects but get no new features; they only receive security fixes while their Filament target is still supported upstream.

Plugin	Filament	Status
`4.x`	v4 & v5	Active — new features + bug fixes (lives on `main`)
`3.x`	v3	End of life — follows Filament v3 EOL
`2.x`	v3	End of life — follows Filament v3 EOL
`1.x`	v2	End of life

See CHANGELOG for migration notes between majors.

Changelog

See CHANGELOG for the list of recent changes.

Contributing

See CONTRIBUTING for details.

Security Vulnerabilities

Review our security policy to learn how to report security vulnerabilities.

Credits

License

The MIT License (MIT). See the License File for more information.

bezhansalleh / filament-exceptions

Package info

Security

Fund package maintenance!

Statistics