Server Error Pages Laravel Package

Getting Started

Start by requiring the package via Composer and letting Laravel auto-discover the service provider:

composer require enniosousa/server-error-pages

Then publish the package's views (and config, if provided) so you can customise the error templates:

php artisan vendor:publish --provider="EnnioSousa\ServerErrorPages\ServerErrorPagesServiceProvider"

Where to look first:

• config/server-error-pages.php (if published) — toggle and behaviour switches.
• resources/views/vendor/server-error-pages/ — the actual error page templates after publishing.
• The package README on GitHub for the current namespace and supported Laravel versions (the v1.1.0 PSR-4 change means the namespace in older docs/snippets may no longer apply).

First use case: replacing Laravel's default bland error pages with branded 404/500/503 screens. Once published, edit the Blade files directly — no package code changes required. Verify by hitting a non-existent route (404) and, in a staging environment, forcing a 500 (e.g. abort(500)).

Implementation Patterns

• Publish-and-own: The intended workflow is publish-once, then treat the Blade templates as part of your app. Commit them and customise freely (branding, support links, tracking snippets).
• Environment-aware behaviour: Keep debug mode off in production so the package's pages actually render; Laravel's APP_DEBUG=true bypasses error pages with the Ignition/Whoops stack.
• Layout inheritance: Typically the error templates extend a shared layout or are dropped in as standalone pages. If you want them to share your app's CSS/JS, publish the views and point them at your resources/views/layouts/app.blade.php.
• Exception handler integration: For finer control, customise app/Exceptions/Handler.php (register() / render()) to map specific exception types to specific pages, rather than relying solely on status-code-based rendering.
• Status-code coverage: Decide which pages matter for your app (401/403/404/419/429/500/503) and only publish/customise those — the package templates are just Blade views, so adding or removing ones you don't need is safe.
• Multi-tenant / branded variants: If you serve multiple brands, publish the views once and use a middleware or view composer to pick the correct branded set at runtime.
• Upgrade pattern (post v1.1.0): After upgrading, composer dump-autoload, then php artisan view:clear and php artisan config:clear, and re-verify the published views still extend the correct layout (the PSR-4 migration may have shifted the vendor view namespace).

Gotchas and Tips

• Namespace change (v1.1.0): The PSR-4 migration likely renamed the namespace/autoload path. Any use statements, service provider registrations, or vendor:publish --provider=... commands from older docs may be stale — copy the current provider FQCN from the README.
• Laravel version support: "Update to ... Laravel framework" implies bumped framework requirements. Check the composer.json illuminate/* constraints before upgrading; pinning an older Laravel will silently keep you on v1.0.x.
• Caches bite after upgrades: In production the view and config caches will keep serving the old compiled templates. Always php artisan optimize:clear (or the individual view:clear / config:clear) after upgrading or re-publishing.
• Debug mode hides your work: The single most common "it doesn't work" issue is APP_DEBUG=true showing the stack trace instead of your error page. Test with APP_DEBUG=false on staging.
• 419 / CSRF and 503 maintenance: These are easy to forget. Confirm CSRF token expiry renders your page, and that php artisan down shows your maintenance view rather than the framework default.
• Exception handler overrides: If your app's exception handler already renders custom responses for certain statuses, the package's views may never be reached. Check Handler::render() first when a page "doesn't update".
• Testing tips: Use feature tests that hit routes and assert assertStatus(404) plus assertSee() on a branded string, so changes to the templates are covered. Force 500 via a test route throwing an exception, not by editing production code.
• Extension point: If the package exposes a config, prefer overriding values in config/server-error-pages.php and re-publishing rather than editing vendor files — vendor edits are lost on the next composer update.