Support Page Laravel Package

Getting Started

1. Install and inspect before wiring anything up.

   composer require networkrailbusinesssystems/support-page
   

   The package is a low-traffic (0 stars, 0 dependents) internal NRBS utility, so treat the README and src/ as the source of truth rather than blog posts. First reads: composer.json (Laravel/PHP constraints), the service provider (register()/boot() tells you what is auto-loaded, what routes are registered, and what is publishable), and config/ for the knobs you will actually touch.

2. Publish what you need, not everything.

   php artisan vendor:publish --provider="NetworkRailBusinessSystems\SupportPage\SupportPageServiceProvider"
   

   If that provider path differs, run php artisan vendor:publish with no arguments and pick the support-page entries from the interactive list. Typical tags are -config, -views, and -migrations; publish views only when you intend to customise them, and migrations only if the package persists submissions (check database/migrations in the vendor directory first).

3. Check routes and the entry point.

   php artisan route:list | grep -i support
   

   You are looking for the path (commonly /support), the route name, and any middleware applied. Hit that URL in a browser before changing config — a working default confirms the service provider, views, and mail/web config are wired correctly.

4. First real use case: an internal "contact the team / raise a support request" form. Set the recipient address and subject in the published config, point the form at your mail transport, submit a test message, and confirm it lands. Only then start styling it to match your app.

Implementation Patterns

Config-first customisation. Most day-to-day changes should be config edits: recipient email(s), subject line, route path, middleware/guard, and any field toggles the package exposes. Keep the published config in version control and drive environment-specific values (recipients, from-address) through .env so staging tickets don't hit the live inbox.

View overrides over vendor edits. Publish the views and edit the copies under resources/views/vendor/support-page/. Never edit vendor/ — the next composer update silently discards it. If the package ships its own layout, the usual move is to swap it for @extends('layouts.app') (or a component) so the page inherits your nav, flash messages, and footer.

Protect it like any other form endpoint. Add auth/verified middleware via config or by re-registering the route in your own routes/web.php with the same controller action. For public-facing deployments, pair it with rate limiting (throttle:) and a honeypot or CAPTCHA — a support form with a mail sink is a spam magnet.

Route ownership. If you need a different path, custom middleware, or a route name your nav can route() to, define the route yourself pointing at the package controller rather than fighting the package's registration. Check route:list afterwards for duplicates; whichever registers last wins, and package providers usually boot before your RouteServiceProvider.

Notifications and queuing. If the package sends mail synchronously, wrap it: either set MAIL_MAILER=log locally so tests don't spam, or extend the controller/handler to dispatch a queued notification. For anything beyond a simple mail — ticketing systems, Slack, Jira — listen for the package's events if it fires them, or override the submission handler entirely; don't bolt side effects into the Blade view.

Testing. In feature tests use Mail::fake() and assert the expected mailable/notification was sent, and RefreshDatabase if migrations are published. Assert both the happy path and validation failures, plus a guest-vs-authenticated access check if you added a guard.

Gotchas and Tips

• Config cache. After publishing or editing the config, php artisan config:clear (and config:cache in deploy) — a cached config is the single most common "my change did nothing" cause with page packages.
• Publish tag names are not guaranteed. If --tag=support-page-config errors, list tags first; guessing tags wastes more time than reading the provider's publishes() calls.
• Laravel version drift. With a small package and a single maintainer, pin the version in composer.json rather than floating, and check the illuminate/* constraints against your app before upgrading the framework. Vendor the view overrides so a breaking view change is visible in your diff, not at runtime.
• CSS assumptions. Bundled views often assume Tailwind or a specific CSS framework. If your pipeline purges classes from vendor/, either add the vendor view path to content in tailwind.config.js or expect unstyled output that looks fine in dev and broken in production.
• Mail configuration failures look like package bugs. A blank success page with no email is usually a MAIL_* or from address issue, not the package. Check storage/logs/laravel.log and try MAIL_MAILER=log to see the rendered message.
• Migrations are one-way in practice. Publishing migrations means you own them; don't edit a published migration after it has run in a shared environment — add a new one.
• Extension points to prefer: config, published views, route re-registration, and event/listener hooks. Subclassing the controller is acceptable but couples you to internals; it should be a deliberate, documented choice.
• Bus factor. With no dependents and no stars, budget for maintaining your fork if the upstream goes quiet — keep your overrides small and documented so a local patch is a five-minute job.