Govuk Laravel Laravel Package

Getting Started

Start by installing the package with Composer and letting Laravel auto-discover its service provider:

composer require anthonyedmonds/govuk-laravel

Then publish the package’s config and frontend assets using the vendor:publish tags documented in the package README. At minimum, publish the config so you can inspect component namespaces, asset paths, and any layout defaults. If you plan to customise markup, also publish the views.

As of 8.7.0 the package also ships mail support (PR #156, “Feature/mail”). After upgrading, check the README for the mail-related publish tags and publish any mail views or mail theme files you intend to customise. This lets you send GOV.UK-styled transactional email from Laravel Mailables without hand-writing the markup, and keeps email templates alongside your web components.

The first practical use case is still a GOV.UK-styled form page: use the package layout for the header/footer, render an error summary, then build fields with the package’s Blade components. For example, a controller returns a view, and the Blade view composes GOV.UK form groups, inputs, radios, checkboxes, and a submit button. This gives you accessible GOV.UK markup without hand-writing the Design System HTML.

The second use case, new in 8.7.0, is a GOV.UK-styled confirmation or notification email. Build a Mailable, point it at the package’s mail views or mail components, pass the same data you would to a web view, and assert the rendered HTML in a test before sending.

Where to look first:

1. The package README and component list, including the new mail section.
2. config/govuk.php after publishing.
3. resources/views/vendor/govuk if you need to override web or mail markup.
4. The GOV.UK Design System examples for the components you use, so you can compare rendered output.
5. The 8.7.0 changelog and PR #156 for the exact mail API and any publish tags.

Implementation Patterns

Compose pages from Blade components. Use the package’s layout and navigation components for consistent GOV.UK page structure, then compose forms and content from components such as error summary, input, textarea, select, radios, checkboxes, button, summary list, table, tabs, details, warning text, and panel. This keeps markup aligned with GOV.UK Frontend and reduces repeated accessibility markup.

Wire Laravel validation into GOV.UK components. Pass $errors into the view and render an error summary near the top of the page. Field components should receive the same name/id used by Laravel validation so error links work. Use old() for repopulating values after validation failures. A common workflow is:

1. Form Request validates input.
2. Controller redirects back with errors on failure.
3. Blade view renders error summary and field-level errors.
4. Field components use old() and the error bag to set values and error classes.

Send GOV.UK-styled mail. With 8.7.0, use the package’s mail views/components inside a Mailable rather than duplicating GOV.UK markup for email. A typical workflow is:

1. Generate a Mailable with php artisan make:mail SubmissionConfirmation.
2. In build() or content(), return a package mail view or your own view that composes the package’s mail components.
3. Pass a small, explicit data array (name, reference, summary rows) rather than the whole model, and keep a plain-text alternative.
4. Render and assert the HTML in a feature test using Mail::fake() plus a direct view render, so markup regressions are caught before deployment.
5. Send through your normal Laravel mailer; keep transport config in config/mail.php, not in the package config.

Keep mail content transactional and concise: a heading, a short body, a summary list for reference data, and a clear call to action. Reuse the same wording and summary-list structure as the corresponding web confirmation page so users see a consistent journey.

Use the Back to top component for long pages. The 8.6.0 release added a “Back to top” feature. Use it at the end of long guidance, tables, or multi-section pages. Ensure the target anchor exists and has a stable id, and keep the link text meaningful for screen readers. Place it after the main content rather than inside form controls. Note that this is a web-only affordance; don’t carry it into email templates.

Adopt the GOV.UK alignment changes deliberately. PR #153 (“Feature/govuk 65”) continued alignment with GOV.UK Frontend, and 8.7.0 builds on that baseline. After upgrading, compare key pages against the GOV.UK Design System examples. This is especially important for forms, error summaries, and components with updated classes or markup. Treat 8.7.0 as a minor release, but still smoke-test your most complex forms and at least one rendered email.

Integrate with your asset pipeline. If you customise GOV.UK Frontend assets, import the package’s CSS/JS according to its documentation, or publish and include the provided assets in your layout. If you use Vite or Mix, keep the GOV.UK asset entry points separate from application-specific styles so upgrades are easier. Email templates cannot rely on external stylesheets, so make sure any new mail views use inline or embedded styles rather than your application bundle.

Override views sparingly. Publish vendor views only for components you genuinely need to change — and, for mail, only the specific mail views you need to brand. Prefer wrapping package components in your own Blade components when you need project-specific defaults, such as consistently adding hints, prefixes, or suffixes.

Gotchas and Tips

• Missing styles or JavaScript: If components render but look unstyled, confirm assets were published and are included by your layout. Clear cached views after publishing or overriding views with php artisan view:clear.
• Mail views look unstyled in some clients: Email clients strip external CSS and often ignore modern layout features. Expect mail output to be more conservative than the web components; test in at least one desktop and one mobile client, and keep a plain-text part. If styles are missing entirely, check that you published the mail views and that asset URLs in the template are absolute.
• Mail view namespace and publish tags: The 8.7.0 mail feature adds new publishable paths. Run php artisan vendor:publish interactively to see the available tags rather than guessing, and re-run view:clear after publishing mail views.
• Error summary links not working: The error summary relies on matching field IDs. Ensure each field’s id matches the validation error key and that the error summary is rendered before the fields.
• Back to top target: The Back to top component needs a valid target. Use a real element ID at the top of the page and test keyboard and screen-reader behaviour. Do not rely only on a visual “top” link.
• Component API changes: Minor releases usually avoid breaking changes, but GOV.UK alignment work and new features such as mail can alter markup or accepted props. Check the changelog and run regression tests on forms, error summaries, customised components, and rendered mail.
• Config caching: If you change package config in production, run php artisan config:cache as part of deployment. Do not edit files in vendor/.
• Debugging markup: Compare rendered HTML with the official GOV.UK Design System examples. Small differences in class names, aria-* attributes, or IDs often explain accessibility or styling issues. For mail, compare against the GOV.UK notification/email guidance where available.
• Extension points: Use published config, published views (web and mail), and your own wrapper Blade components. Avoid forking the package for small presentation changes; keep custom GOV.UK components in your app’s resources/views/components directory and custom mail views in resources/views/vendor/govuk or your own mail view namespace.
• Version alignment: Keep the package version reasonably aligned with the GOV.UK Frontend version it targets. After each upgrade, test one representative page per major component category rather than only the page you changed — and, from 8.7.0 onward, render one representative email as part of the upgrade checklist.