Weave Code
Laravel Oops Laravel Package
naiskit/laravel-oops
Laravel Oops is a lightweight package for cleaner error handling in Laravel apps. It helps replace raw exceptions with friendly, customizable error pages and clearer responses, making failures easier to understand for users and developers. Simple to install and configure without disrupting your work...
A friendly Laravel error page package that makes unexpected errors a little less frustrating.
Frequently asked questions about Laravel Oops
- How do I install naiskit/laravel-oops in a Laravel app?
- Install it with Composer using composer require naiskit/laravel-oops. The package is a drop-in Laravel exception renderer with a service provider and error page composer, so Laravel 11-13 auto-discovery should wire it without middleware, database, cache, or queue setup. Publish config or language files only if you need to customize the defaults.
- What Laravel and PHP versions does Laravel Oops support?
- Laravel Oops v2 is validated against Laravel 11, 12, and 13 on PHP 8.2, 8.3, and 8.4. CI also runs PHPStan/Larastan level 5 and coverage reporting. Apps on PHP 8.1 or older Laravel releases cannot adopt v2 without upgrading first.
- How do I customize Laravel Oops error page themes and copy?
- The v2 design separates theme, which is a Blade view for layout and visuals, tone, which is a language file for copy voice, and locale, with English and Indonesian shipped. Override them through Laravel's standard resources/views/vendor/oops and lang/vendor/oops paths, or publish the language files. Release notes also describe config keys such as oops.theme, logo, colors, background image, mascot, and footer settings, but confirm the actual tag source because the notes are contradictory.
- How do I publish Laravel Oops config and language files?
- Use Laravel's vendor:publish flow to publish the package config, and publish the language files with the oops-lang tag. For view overrides, place your Blade files under resources/views/vendor/oops rather than editing vendor code. Keep your published overrides in version control so error-page changes are reviewable.
- Does Laravel Oops leak exception messages or stack traces?
- The package includes SECURITY.md and a Feature SecurityTest asserting that exception messages, stack traces, and file paths never reach the rendered page, including when APP_DEBUG is true with forced rendering. That directly addresses the worst failure mode for error-page packages. Still verify the shipped tag yourself, because the release notes contradict themselves on whether oops.force is removed or configurable.
- What is OOPS_FORCE or oops.force in Laravel Oops?
- OOPS_FORCE or oops.force appears intended to force friendly error rendering even when debug behavior would otherwise expose framework details. The v2 release notes list it as removed and also describe it as configurable, and the security test references oops.force, so treat the actual source and README as the source of truth. Do not enable forced rendering in production until you have confirmed exactly what it overrides.
- How do I localize Laravel Oops error pages for non-English locales?
- Laravel Oops v2 ships English and Indonesian tone files and no longer follows app.locale through OOPS_LANG. Apps serving other locales will render English error pages unless you author tone and lang files. Add overrides under lang/vendor/oops and test the rendered page for each supported locale.
- Can I remove the Powered by Naiskit branding from Laravel Oops?
- Powered by Naiskit is on by default, so client-facing or white-labeled products must confirm the off switch exists and is wired. Release notes mention footer and show_footer settings but also contradict themselves about what was removed. Render a production-like error page and inspect the HTML before shipping to customers.
- How do I upgrade Laravel Oops from v1 to v2?
- Treat v2 as a config-shaped breaking upgrade: five env vars remain, copy moves to publishable lang files via --tag=oops-lang, and many v1 knobs are deleted. Because Laravel returns null for unknown config keys, removed options can fail silently to defaults, so audit config, publish language files, and visually test each error page. The provided assessment did not find a documented v1-to-v2 mapping table, so confirm the upgrade guide in the actual repository.
- What happens if a custom Laravel Oops theme view is missing or broken?
- The provided assessment flags this as an open question rather than documented behavior, so do not assume a safe fallback. Test a missing or malformed theme view before relying on custom templates, because an error page that throws creates a double fault. Keep error templates simple and have a known-good bundled or default view available for production.
Weaver
How can I help you explore Laravel packages today?