Laravel Oops Laravel Package

Product Decisions This Supports

• Treating error pages as a product surface, not an afterthought. v2.0.0 formalizes two distinct page designs (default open two-column layout vs. legacy astronaut) and six voice presets (formal, casual, fun, wise, brief, technical). That turns "what does a user see when we fail?" into an explicit, reviewable product choice rather than an engineering default — and lets you pick a different answer for customer-facing surfaces vs. internal tools (e.g. technical for admin back-offices, formal or casual for public checkout).
• Support operations and incident triage. The standout capability is the per-render reference code: every error page generates a code, logs it alongside the real exception (message, class, stack trace; 5xx at error, everything else at warning), and surfaces it on the page — optionally embedded in the "what to do next" support line via {ref}. This is a product decision about time-to-resolution and escalation cost: a user-reported code maps directly to a log entry, removing the "can you send a screenshot / what time was it / what URL" loop from support.
• Brand and voice consistency without a design project. Themes and tones are single Blade views and single lang files, publishable and overridable per app (resources/views/vendor/oops/themes/, lang/vendor/oops/{lang}/tones/). A custom tone only needs the keys it changes; everything else inherits from formal. That is a genuinely cheap path to "our error pages sound like us" — days of work avoided, not weeks.
• Localization scope decisions, made explicit. OOPS_LANG is a hard en/id choice and no longer follows app.locale. For a bilingual product this is a fork in the road: either the error page is a deliberate exception to your locale strategy, or the package is the wrong fit. Worth deciding consciously, not discovering in QA.
• White-labeling / attribution. "Powered by Naiskit" is on by default and controlled by OOPS_POWERED_BY. For B2B or embedded deployments, whether a third-party credit appears in a customer's failure moment is a brand and legal-review question that now has a single flag rather than a code change.
• Security and compliance sign-off as a gate, not a hope. The added SECURITY.md and security test suite assert exception messages, stack traces, and file paths never reach the rendered page even with APP_DEBUG=true + forced rendering. That converts a recurring security-review objection ("does this leak internals on 500s?") into a documented, tested property — useful evidence in vendor questionnaires and pen-test prep.
• Build vs. buy, decided in favor of buy. Rendering, theming, i18n, logging correlation, and a CI matrix across PHP 8.2/8.3/8.4 × Laravel 11/12/13, plus PHPStan/Larastan level 5 and Dependabot, is not worth owning in-house for an app whose core value is elsewhere.
• Roadmap input on error-handling UX. Reference codes plus structured, tone-separated copy create a foundation for later, product-visible work: surfacing recent incident codes in a status page, per-status tone overrides for high-stakes flows (payments vs. a 404), and measuring "user-reported error → resolved" as a support metric.

When to Consider This Package

Consider adoption when:

• You are on Laravel 11, 12, or 13 with PHP 8.2–8.4 — the declared, CI-tested support matrix. Anything older is unsupported.
• Your application has human-visible HTML error surfaces, especially 403/404/419/429/500/503 on customer-facing flows where trust and clarity matter.
• Your support workflow involves users reporting failures, and you want reference codes correlated to logs rather than free-text bug reports.
• You want brand-consistent, voice-controlled error copy but do not want to staff a design system effort for a page users see only when something breaks.
• You have a security review that will ask about debug-mode leakage and stack traces.
• You are content with en and id only, or willing to publish and maintain your own lang files for other locales.
• You accept a fixed visual design with limited token overrides rather than full control of markup.

Look elsewhere — or stay pinned to v1 — when:

• Dark mode / OS-preference following is a requirement. v2 removes light/dark/auto and per-visitor theme detection; each theme has exactly one look. This is a real accessibility and user-expectation regression for some products.
• Your locale strategy is "follow app.locale, always." v2 hard-codes OOPS_LANG to en|id. Multi-locale products (5+ languages) should assume they will own the lang files entirely, and a per-request locale switch is no longer free.
• You depend on v1 configuration. v2 is breaking: OOPS_FORCE, oops.statuses, oops.view, oops.messages, oops.default_message, oops.ui, oops.quotes_path, OOPS_QUOTE_GENRES, every OOPS_THEME_* / OOPS_COLOR_* / OOPS_LOGO_* variable, OOPS_ICON_ALIGN, OOPS_BACKGROUND_IMAGE, and OOPS_SHOW_FOOTER are gone, replaced by five settings. Treat this as a migration project, not a composer update.
• You need the random quote library (resources/quotes/, oops:quote, QuoteRepository, genres, session-based no-repeat). Removed; the surviving equivalent is the fixed per-status quotes inside the wise tone.
• You need per-status custom views — removed in favor of one view per theme.
• Your errors are predominantly JSON/API responses. This renders HTML pages; it does not solve API error envelopes.
• You need the full config-driven surface described in the "Added" block — see the caveat below.

Caveat the release notes impose on any roadmap commitment: the v2.0.0 notes are internally inconsistent. The "Removed" section deletes OOPS_SHOW_FOOTER, OOPS_BACKGROUND_IMAGE, OOPS_THEME_*, dark/light mode, mascots, insight lines, and the quote library — while the "Added" and "Changed" sections describe adding oops.theme.icon_align, insight, support, oops.show_footer, oops.theme.background_image, oops.theme.mascot, configurable light/dark forcing, color/accent overrides, and logo replacement. Some "Added" items also appear truncated ("Repl..."). Before quoting capabilities to stakeholders or sequencing an upgrade, verify against the actual tagged source and config/oops.php; the config surface is the thing most likely to differ from the notes. Do not plan a release around the "Added" list until that is reconciled.

How to Pitch It (Stakeholders)

To executives (one paragraph): This is a low-cost, well-maintained dependency that upgrades how our product behaves at its worst moments — when a user hits a 404, a permission wall, or a 500. Three things matter commercially. First, trust: instead of raw framework output or a generic "whoops," users get a branded page that explains what happened in a voice we chose, in one of six tones, with a clear next step. Second, support cost: every page carries a reference code that is logged against the real exception, so a user's report resolves in one lookup instead of a back-and-forth — a direct reduction in handling time per incident. Third, security posture: the package ships a documented security policy and an automated test suite proving exception messages, stack traces, and file paths never render, including in debug mode, which answers a standard security-review objection with evidence. It is free, tracked against Laravel 11–13 and PHP 8.2–8.4, and maintained with static analysis and dependency automation — so the cost is adoption, not ownership.

To engineering: Drop-in for Laravel 11–13 on PHP 8.2–8.4. Rendering is composer-driven, themes are single Blade views, tones are single lang files — both publishable and overridable per app without forking. Reference codes are generated per render and logged at error for 5xx and warning otherwise, correlated to the underlying exception. CI covers the full PHP × Laravel matrix, PHPStan/Larastan level 5, and coverage, with Dependabot on composer and actions. Two things to flag: v2.0.0 is breaking — the config surface collapses from dozens of variables to five (OOPS_ENABLED, OOPS_THEME, OOPS_TONE, OOPS_LANG, OOPS_POWERED_BY), so budget a migration rather than a patch bump, and pin v1 if we need the old behavior mid-cycle. And dark mode is gone — each theme has one fixed look regardless of the visitor's OS preference; if that is a requirement for us, we should say so now, because it is a deliberate removal, not an oversight. Finally, before we scope work, reconcile the release notes against the tagged source: the removed and added lists contradict each other on footer, background image, mascot, insight, color overrides, and theme mode, and the notes appear truncated.