Govuk Laravel Laravel Package

Technical Evaluation

Architecture fit. anthonyedmonds/govuk-laravel has until now been a pure presentation-layer package: it wraps the GOV.UK Design System (govuk-frontend HTML/CSS/JS) in Laravel Blade components, plus layouts and form/validation helpers. Release 8.7.0 changes that boundary. The single change in this release — "Feature/mail" (PR #156) — introduces a mail-notification capability, which means the package now touches a delivery concern (Laravel's mailer, notification classes, mail-view rendering) rather than only HTTP responses. That is a materially wider footprint: mail is asynchronous-ish, externally visible to users, rendered by clients we don't control, and potentially triggered by queue workers. It remains a good architectural fit for server-rendered Laravel services needing GDS compliance (GOV.UK-styled transactional email is a real gap most teams fill with hand-rolled templates), and it is still the wrong shape for SPA/API-first products. But we should now evaluate it as presentation + notification templating, not presentation alone.

Integration feasibility. Still a standard Composer install with package auto-discovery; views and assets remain publishable. 8.7.0 is a minor bump (8.6.0 → 8.7.0), so semver says non-breaking — but minors can add service-provider registrations, config keys, publishable namespaces, and Blade component names that collide with ours. Integration is a composer update plus a re-publish check, plus a new step for mail: inspect what the mail feature actually adds (mail views? a Notification base class? a mail config file?) and confirm it is inert until deliberately used. The critical question is whether the package registers anything on the mail side unconditionally at boot.

Technical risk. Low-to-moderate for this release; moderate for the dependency overall.

• The release notes are again extremely terse — one PR title, no migration notes, no detail. "Feature/mail" is not self-describing: it could be GOV.UK-styled mail templates, a Notifiable trait, a mail-channel abstraction, or a set of Blade components for email. We cannot size the change until we read the diff.
• Mail is a new blast radius. An unexpected service-provider binding, config default, or published view can change behaviour in a code path (notifications) that is often untested and frequently fires from queues.
• The unresolved items from 8.6.0 — notably "GOVUK 65" and the "back to top" component's provenance — are not addressed by this release. If we have not yet adopted 8.6.0, we now step two minors.
• The package is effectively single-maintainer, which remains the dominant long-term risk; it is mitigated by the fact that it is a thin wrapper we could fork or vendor — though a mail feature makes a fork slightly heavier to maintain.
• Compatibility is coupled to the upstream govuk-frontend version, and now also to Laravel's mail/notification APIs, which change more often than the design system does.
• Published-view overrides remain the most common source of silent divergence after upgrades, and mail views will be the newest and least-exercised overrides.

Key questions.

1. What exactly does "Feature/mail" ship — mail-view templates, Blade mail components, a Notification base class, a mail-channel driver, or config? Which files are publishable?
2. Is the mail capability opt-in and inert by default, or does the service provider register bindings/config/publish tags on every install?
3. Does 8.7.0 add or change any config keys, service-provider registrations, or Blade component namespaces that could collide with existing application code?
4. Does it require a minimum Laravel/PHP version bump (mail APIs differ meaningfully across Laravel majors)?
5. Are mail templates plain Blade, Markdown, or GOV.UK-styled HTML with inline CSS? How do they render in Outlook and other constrained clients?
6. Do the new mail templates meet the same accessibility bar (semantic headings, contrast, alt text, plain-text alternative) as the web views?
7. Still outstanding from 8.6.0: what is "GOVUK 65", and which govuk-frontend version does the current line require?
8. Is "back to top" an upstream Design System component or package-local, and what is its accessibility provenance?
9. Have any existing Blade component signatures, slots, or config keys changed across 8.6.0 → 8.7.0?
10. What is the supported Laravel/PHP matrix, and is it covered by CI — including the mail path?

Integration Approach

Stack fit. Targets Laravel with Blade and server-rendered forms; complements Laravel's validation, old(), and error bags. With 8.7.0 it also sits alongside Laravel's notification/mail system, which is a natural pairing — GOV.UK-consistent transactional email is otherwise assembled by hand and drifts from the web UI. No Tailwind or JS framework required. Strong fit for UK public-sector, local authority, NHS-adjacent, and regulated services; a poor fit where the brand is not GOV.UK. Note that the mail feature is only relevant if we actually send user-facing email — if we do, it is a small win; if we don't, it is dead weight we should leave untouched.

Migration path. Treat as a patch-level upgrade with one unknown: branch, composer update anthonyedmonds/govuk-laravel, then read the 8.7.0 diff (specifically the mail PR) before merging. Diff vendor/ views and assets against our published copies and re-publish selectively. Establish first what version is actually pinned in composer.json/composer.lock — the practical path is likely 8.6.x → 8.7.0, but if we are still on 8.5.x we should step through 8.6.0 and read its notes too.

Compatibility. Verify PHP/Laravel constraints against our runtime before upgrading, with particular attention to the mail/notification APIs (they differ across Laravel majors). Check that the bundled govuk-frontend asset version still matches what design/content signed off; confirm GOVUKFrontend.initAll() still initialises after any JS changes; check our mailer configuration (SMTP/API driver) is untouched by the new package code. Confirm browser-support policy if we still serve legacy browsers — and separately confirm email client support if we adopt the mail templates.

Sequencing.

1. Inventory current version, published overrides, bespoke components overlapping with "back to top", and any existing hand-rolled mail templates that the new feature might supersede.
2. Pin baseline; capture visual regression and accessibility baselines (axe/pa11y) on key web journeys, and snapshot current transactional emails (rendered HTML) as an email baseline.
3. Upgrade in a branch; read the mail PR diff; re-publish and diff views/assets.
4. Run visual regression and accessibility scans; manually test the new component with keyboard and screen reader.
5. Mail separately: enable the feature only in a non-production environment first, render every new template, test in at least Outlook, Gmail, and Apple Mail, verify plain-text alternatives and link/contrast accessibility, and confirm nothing sends unless a notification explicitly uses it.
6. Adopt "back to top" incrementally — one template or journey first — only if content design has agreed the pattern.
7. Adopt mail templates one notification at a time, starting with the lowest-risk transactional email (e.g. a receipt), not password reset or security alerts.
8. Roll out with a documented rollback (revert lockfile + re-publish previous assets and mail views).

Operational Impact

Maintenance. Low but rising. Web-side cost is unchanged: periodic minor upgrades, view-override reconciliation, asset re-publishes, automated with Dependabot/Renovate plus a CI job that fails on uncommitted view diffs. Mail adds a second surface to keep in sync — mail views are overridden and diverge just like web views, but they are far less visible in day-to-day testing, so drift is discovered by users rather than by developers. Keep overrides to the minimum viable set on both surfaces.

Support. Community OSS with no SLA and a single primary maintainer; the mail feature is brand new, so it has the least field-testing and the thinnest issue history of anything in the package. Name an internal owner (frontend/platform for web; the team that owns notifications for mail) and an escalation path — GitHub issues upstream, fork-and-patch internally if a fix is blocking. Budget a small contingency for upstream lag on accessibility defects, and note that email-client quirks are unlikely to be fixed upstream quickly.

Scaling. Web side remains presentational and scales with the app; the real considerations are the asset pipeline (compile and CDN-cache the GOV.UK CSS/JS once, fingerprint for cache busting) and template-level usage discipline. Mail scales differently: rendering cost is trivial, but volume, deliverability, and provider rate limits become the constraints — and if notifications are queued, failures surface in worker logs rather than request logs. Mail templates with heavy inline CSS should be compiled/cached rather than rebuilt per send if volume is high.

Failure modes.

• Unpublished view overrides silently shadowing upstream fixes, including accessibility fixes — now on two surfaces (web and mail).
• Missing or double-initialised JS bundle → non-functional details, accordions, and the back-to-top behaviour.
• CSS collisions with application stylesheets or a competing design system.
• New: mail templates rendering incorrectly in constrained clients (Outlook), or being delivered without a plain-text alternative.
• New: notification classes added or bound by the package interacting with our existing notification/mail configuration, or a queued notification failing silently.
• New: accessibility regressions in email that automated web scans will never catch.
• Breaking Blade component API changes in a future minor/major that only surface at render time, not at install time.
• Component deprecation upstream without a corresponding package release, leaving us on an unsupported pattern.
• Bus factor: an unmaintained package mid-service-life, requiring an internal fork — now a slightly larger fork.

Ramp-up. A Laravel developer comfortable with Blade is productive in roughly one to two days; the mail feature is familiar Laravel territory (notifications, mail views) and adds little. Fluency in GOV.UK conventions (error summaries, one-thing-per-page, content style) takes a few weeks and is better sourced from design/content communities of practice than from the package. Allocate half a day of onboarding to the override and upgrade workflow specifically, plus a short session on mail-template testing and client coverage if the mail feature is adopted.