Laravel Mautic Laravel Package

Product Decisions This Supports

• Build vs. buy for marketing automation glue. This package is the "buy/adopt" answer to a recurring question: do we build and maintain our own Mautic API client, token store, and OAuth plumbing, or adopt a maintained Laravel integration? v1.1.0 materially strengthens the adopt case by shipping the OAuth browser flow, canonical callback URL resolution, and an adoption guide — the exact work a team would otherwise scope as a multi-sprint internal project.
• Roadmap sequencing for marketing/messaging features. Because authentication, credential resolution, and diagnostics are now handled by the package, roadmap items like contact sync, segment membership, campaign triggers, and email dispatch can be estimated as feature work rather than infrastructure work. This shifts the "enabling work" line item out of the roadmap and reduces the risk premium on marketing-integration epics.
• Multi-tenant and self-service onboarding use cases. The combination of connection allowlisting, per-connection redirect_uri, and host-defined authorization via OAuthBrowserAuthorizer makes it viable to let a customer connect their own Mautic instance from inside the product. That unlocks a self-serve integration surface (connect/disconnect, per-tenant credentials) instead of a services-led, per-customer configuration exercise.
• Security and compliance posture decisions. Two defaults are decision-grade rather than cosmetic: package OAuth routes are disabled by default, and host authorization denies by default. Both mean the secure configuration is the default configuration, which simplifies security review and lowers the chance of shipping an accidentally open authorization endpoint.
• Deployment and ops model choices. Laravel environment-repository support for client secrets (retaining process-environment compatibility and custom providers) answers the "where do secrets live?" question — including for PHP-FPM, CLI, scheduler, and queue workers, and with cached configuration. This lets you decide between env-injected secrets and a secrets manager without forking the package.
• Operational supportability decisions. mautic:oauth:callback-url (read-only) and sanitized credential availability reporting in mautic:diagnose reduce the cost of the single most common integration support ticket: "why won't it connect?" That is a direct support-load and time-to-resolution lever, not just a developer convenience.
• Migration/upgrade planning. The 1.0.0 → 1.1.0 path is additive: no new migrations, no token-storage changes, existing token records and APP_KEY preserved, and host-owned OAuth routes remain supported. This makes the upgrade plannable as routine maintenance rather than a risky migration project.
• Buy-in on scope boundaries. The release explicitly puts the login/consent UI and the authorization policy in the host application's hands. That is a scope decision PMs should surface early: the package gives you the mechanism, your product owns the UX and the access policy.

When to Consider This Package

Consider adoption when most of the following hold:

• The product is a Laravel 12 or 13 application on PHP 8.4/8.5 (the release is validated on exactly these combinations).
• There is an existing or planned Mautic instance that the business already treats as the system of record for marketing automation; this package is an integration layer, not a replacement for Mautic.
• You need per-connection OAuth rather than a single hard-coded global credential — i.e., multi-tenant, multi-brand, or customer-supplied Mautic hosts.
• You want host-controlled authorization policy: you have (or will build) your own permission model and consent screen, and you want a package that defaults to deny until you bind an authorizer.
• Secret management is a live concern — cached config, multiple runtime contexts (web, CLI, scheduler, queues), and a preference for env or custom credential providers over credentials committed to config files.
• Your team values diagnosability: a read-only callback-URL command and sanitized credential reporting are worth more to you than a package that hides its internals.
• You are comfortable owning published-config merges: if you have published config/mautic.php, you must manually merge the new oauth.routes settings and must not run vendor:publish --force.

Look elsewhere or defer when:

• You are on older Laravel or PHP versions — nothing here indicates backward support, and the release is validated only on 12/13 × 8.4/8.5.
• You need a hosted, vendor-supported SaaS connector with an SLA; this is a package you operate, and live Mautic plus opt-in MariaDB acceptance tests were not rerun for this release, so real-world verification of the new OAuth paths is on you.
• You require complete out-of-the-box OAuth UX. Routes ship disabled and authorization denies by default; expect host-side work for consent screens, access policy, and route enablement before anything connects.
• Your integration is high-volume batch/bulk sync where a package-level HTTP client is the wrong abstraction — evaluate dedicated sync or ETL tooling instead.
• Your stack is not PHP/Laravel; the value is concentrated in Laravel conventions (service container bindings, config repository, Artisan commands, route middleware).
• Your security model forbids host-adjacent callback routes entirely and mandates a separate authorization service — technically feasible via host-owned routes, but you are then using a fraction of the release's value.

How to Pitch It (Stakeholders)

For executives: This release converts a bespoke integration project into a maintained dependency. It adds opt-in OAuth so customers or business units can connect their own Mautic instance securely, with secure-by-default behavior (routes off, authorization denies unless explicitly granted), per-connection allowlisting, and built-in diagnostics that shorten support cycles. The upgrade is low-risk: no database migrations, no token re-issuance, existing connections and host-owned routes keep working. Net effect is less engineering spent on plumbing and a faster, more credible path to self-serve marketing integration.

For engineering: v1.1.0 adds opt-in OAuth authorization and callback routes (disabled by default) with a host-bound OAuthBrowserAuthorizer that denies by default, connection allowlisting, and configurable route name, prefix, middleware, and result route. Callback URLs resolve canonically from trusted app.url, with an explicit per-connection redirect_uri taking precedence. Client secrets can now come from Laravel's environment repository while remaining compatible with process-environment and custom credential providers. Two operational commands help: read-only mautic:oauth:callback-url, and sanitized credential availability reporting in mautic:diagnose. Two fixes matter for correctness: result redirects now emit a relative Location header instead of rebuilding the destination from the request Host, and callbacks from replaced authorization attempts preserve the active session so the newer flow can complete. Upgrade notes: merge the new oauth.routes keys into published config/mautic.php manually — do not vendor:publish --force; supply the client secret via process environment when config is cached (PHP-FPM, CLI, scheduler, queues) and restart long-running workers after config or env changes; read the OAuth host adoption guide before removing superseded host infrastructure. Validation covers all four PHP 8.4/8.5 × Laravel 12/13 CI combinations with Pint and Larastan level 8 clean (334 tests passed on PHP 8.5/Laravel 13, 7 opt-in tests skipped); live Mautic and opt-in MariaDB acceptance tests were not rerun, so plan a staging validation of the OAuth flow before relying on it in production.