Custom Error Pages Implementation

Overview

This document provides technical documentation for implementing custom error pages using the ErrorsPage module. It describes the components, configuration options, and implementation details for creating and managing custom error pages in your application.

Technical Components

Models

• Setting: Stores error code configurations with associated images
• Report: Logs error reports with details like status code, message, file, and line

Traits

TenantInteractsWithErrorsPage

namespace Modules\ErrorsPage\Traits;

// Trait for tenant models to interact with error pages
trait TenantInteractsWithErrorsPage
{
    // Relationship to error page settings
    public function settings(): HasMany;
    
    // Relationship to error reports
    public function reports(): HasMany;
}

Configuration

The module provides a settings page accessible through the Filament admin panel. The configuration includes:

Error Code Settings

• Error code (e.g., 404, 500)
• Custom image for the error page
• Active status

Implementation

1. Setup

After installing the module, you need to:

1. Add the TenantInteractsWithErrorsPage trait to your tenant model (typically Company or Team)
2. Configure error pages through the Filament admin panel

use Modules\ErrorsPage\Traits\TenantInteractsWithErrorsPage;

class Company extends Model
{
    use TenantInteractsWithErrorsPage;
    
    // Rest of your model
}

2. Creating Custom Error Pages

1. Navigate to the ErrorsPage settings in your Filament admin panel
2. Create a new error page configuration:
   • Enter the HTTP error code (e.g., 404, 500)
   • Upload a custom image to display on the error page
3. Set the APP_DEBUG environment variable to false in your .env file (this ensures custom error pages are displayed instead of detailed debugging information, which should only be shown in development environments)

💡 Important Tips

• Internal Server Errors (500): The module automatically handles all internal application errors (exceptions, fatal errors, etc.) and maps them to error code 500. If you want to provide a custom page for these internal errors, make sure to configure an error page for code 500.

• Livewire Integration: This module replaces Livewire's default error modal with your custom error pages, providing a more consistent user experience across your application.

3. Error Handling

The module automatically:

1. Intercepts HTTP errors with configured error codes
2. Displays the custom error page with the configured image
3. Logs error reports for tracking and analysis

Error Reporting

The module includes error reporting functionality that:

1. Captures error details (status code, message, file, line)
2. Associates errors with the current tenant
3. Provides a reporting interface in the admin panel

Best Practices

1. Common Error Codes: Configure custom pages for common error codes (404, 500, 403)
2. Optimized Images: Use appropriately sized and optimized images for error pages
3. Consistent Branding: Maintain consistent branding in your error pages
4. Helpful Messages: Include helpful messages and navigation options on error pages
5. Regular Monitoring: Regularly review error reports to identify and fix issues