Contact Plugin Laravel Package

Getting Started

• Prerequisites: A working PyroCMS / Streams Platform application on a compatible Laravel version. This is an addon, not a standalone Laravel package — it will not install usefully into a vanilla Laravel app.
• Install:
  • composer require anomaly/contact-plugin
  • Run php artisan addon:list to confirm the addon was discovered, then install it with php artisan addon:install anomaly/contact-plugin (use the exact slug reported by addon:list).
  • Check addon.json / composer.json inside the vendor directory first — it is the fastest way to confirm the addon slug, namespace, supported Streams Platform version, and whether migrations/seeders exist.
• Where to look first:
  1. resources/views/ — the contact form markup and the field names it posts.
  2. src/ — the plugin/module class, routes, and any submission handler or mailer.
  3. resources/config/ and resources/lang/ — recipient/settings keys and labels.
  4. routes.php / service provider — the actual form action URL and route name.
• First use case: get one form working end-to-end before touching design. Configure mail (MAIL_MAILER=log initially), set the recipient address in the addon settings or control panel, embed the form view on a page, submit a test message, and verify both the log entry and the redirect/confirmation behavior.

Implementation Patterns

• Rendering the form: Include the addon's view from your page/theme (e.g. {% include "anomaly.contact_plugin::form" %} or @include(...), depending on the registered view namespace). If a Twig function/tag is exposed by the plugin, prefer that over hardcoding an include path so upgrades are less likely to break your templates.
• Overriding views without forking: Copy the addon view into your theme or app view path using the same namespaced path and edit the copy. Keep the field name attributes identical unless you also update the handler/validation — the handler expects specific keys.
• Server-side handling: The addon typically validates via Laravel's validator and then either mails a notification or persists a submission. If you need CRM/storage integration, hook in with a listener/observer or replace the controller action rather than editing vendor code.
• Custom fields: Add fields in the view and extend validation in a small custom controller or form request that wraps the addon's logic. Keep spam defenses (honeypot field, timestamp, CAPTCHA) in the same layer so they cannot be bypassed by posting directly to the route.
• Settings-driven behavior: Read recipient address, subject, and success message from the addon config/settings rather than hardcoding them. Cache-safe pattern: resolve settings in the controller, pass into the mailer/view.
• Mail integration: Send notifications through Laravel's Mail facade so your app's mailer/queue config applies. Wrap the send in a queued job if you expect volume; a synchronous send in the request cycle is the usual weak point.
• Localization: Put labels, validation messages, and the success message in the addon's resources/lang files (or override them) so multi-language sites don't require template duplication.
• Testing workflow: Use MAIL_MAILER=log plus a feature test that POSTs to the route with valid and invalid payloads, asserting validation errors and the redirect. This is the cheapest way to pin down behavior when documentation is absent.

Gotchas and Tips

• Low adoption risk: With zero stars and zero dependents, treat this as lightly maintained. Pin the exact version in composer.json, read the source before relying on any behavior, and expect to own fixes. Check the last commit date and the Streams Platform constraint before upgrading your CMS.
• Install name mismatch: Composer package name and addon slug are not always identical. Always verify with php artisan addon:list; a failed addon:install is usually a slug or namespace typo, not a code problem.
• Migrations and reinstall: If the addon stores submissions, changing schema means addon:uninstall / addon:install cycles, which can drop data. Back up before reinstalling, and never reinstall on production casually.
• View resolution order: Overrides are resolved by namespace. If your edited view "doesn't take effect," confirm which path the view finder is actually hitting (php artisan view:clear, then check the rendered source), and watch for a theme-level copy shadowing your app-level copy.
• Route/action drift: The form's action may be a named route or a hardcoded slug. After install, run php artisan route:list and grep for the contact route; if you change the page slug or embed the form elsewhere, hardcoded actions will silently 404 or post to the wrong place.
• CSRF and AJAX: If you convert the form to AJAX, include the CSRF token and session cookie, and render validation errors from the JSON response. A common failure is a 419 that looks like a validation bug.
• Mail deliverability: Test with log and smtp/Mailtrap before production. Set a real MAIL_FROM_ADDRESS on your domain, configure SPF/DKIM, and set a reply-to from the submitted email — otherwise notifications land in spam or replies go nowhere.
• Spam and abuse: A bare contact form with no rate limiting gets hammered. Add throttling (throttle middleware) and a honeypot at minimum; CAPTCHA only if the traffic justifies the UX cost.
• Debugging checklist: storage/logs/laravel.log, php artisan route:list, php artisan addon:list, php artisan view:clear, and a manual POST via curl to isolate whether the failure is in routing, validation, or mail.
• Extension points to prefer: events/listeners around submission, view overrides, config/settings, and a thin custom controller. Avoid editing vendor files — you will lose changes on composer update, and with this package there is no upstream momentum to get fixes merged.
• Upgrade caution: Streams Platform majors have historically changed addon APIs. Before upgrading the CMS, run the form's feature test and inspect the addon's composer.json constraint; if it is unmaintained, budget for forking the package into addons/ and maintaining it locally.