Acorn Mail Laravel Package

Technical Evaluation

Scope note: No prior assessment exists, so this establishes the baseline for the package at v2.0.0. The release notes describe a mail-configuration integration for the Roots/Acorn ecosystem (Sage/Bedrock/Trellis), sitting between WordPress and Laravel's mail subsystem. Package identity, ownership, and release cadence should be confirmed before this baseline is treated as authoritative.

Architecture fit. The package is a thin configuration/integration layer over Laravel's mail transport, hosted inside the Acorn service-provider lifecycle. That is a good architectural fit — it is replaceable, small in surface area, and does not own application logic. The tradeoff is that it inherits Laravel's config contract wholesale: v2.0.0 is hard-coupled to Acorn v6 → Laravel v13 → PHP >=8.3. Effective blast radius is therefore "any site whose mail breaks," not "any site that uses the package."

Integration feasibility. Feasible but multi-step. Three breaking axes land simultaneously: framework major (Acorn v6), language floor (PHP 8.3), and an environment-variable rename (MAIL_ENCRYPTION → MAIL_SCHEME). The highest-friction item is not the rename itself but the published-config caveat: any project that ran vendor:publish for config/mail.php retains a local copy keyed on encryption, so the upstream fix in this release is silently inert. That turns a routine dependency bump into a config-drift audit across every project.

Technical risk.

• Silent failure over loud failure. The bug being fixed caused SMTP sends to fall back to PHPMailer defaults, breaking SSL on port 465. The failure mode is deferred and non-obvious — mail appears to send and doesn't arrive. Regression risk on upgrade is the same shape.
• Version skew. Sites still on Acorn ≤5 must pin v1.0.4. If any project uses a permissive constraint (*, ^1 || ^2), Composer may resolve into v2.0.0 on an incompatible stack and fail hard, or worse, partially.
• Triple-lock upgrade. Acorn v6 + PHP 8.3 + env rename cannot be staged independently in most Roots setups, compressing the change window.
• Key questions.
  1. How many projects/environments run Acorn ≤5, and which are pinned vs. floating?
  2. Which projects have a published config/mail.php, and how do we detect that automatically?
  3. Where do environment variables live besides .env — Trellis vault, CI secrets, host-level config, container envs?
  4. Is MAIL_SCHEME read by Acorn v6 natively, or does the package carry the shim? Determines whether the package is optional or required post-upgrade.
  5. What is the maintainer/bus factor and the supported lifetime of the v1.0.4 line?

Integration Approach

Stack fit. Standard Composer dependency in a Roots project; configuration flows through .env (Bedrock) and, where applicable, Trellis-provisioned environment templates. No runtime service, no datastore, no network surface beyond the mail transport it configures — low coupling, cleanly removable if we later choose to inline the config.

Migration path.

1. Inventory: enumerate projects, Acorn version, PHP version, and presence of a published config/mail.php (a git ls-files config/mail.php-style check per repo).
2. Reconcile config: for projects with a published copy, either re-publish or diff against the upstream roots/acorn version — this must happen in the same change as the version bump, not after.
3. Rename environment variables everywhere: .env, .env.example, CI secrets, Trellis vault entries, deployment manifests. Keep MAIL_ENCRYPTION alongside MAIL_SCHEME only as a short-lived transition aid, never as the steady state.
4. Constrain Composer: ^2.0 for upgraded projects, exact 1.0.4 for projects remaining on Acorn ≤5. Avoid open-ended constraints.

Compatibility. Two supported tracks exist after this release — v2.0.0 (Acorn v6 / Laravel 13 / PHP 8.3+) and v1.0.4 (Acorn ≤5). Treat that as a deliberate fork and document it internally; do not let the two tracks mix within one codebase or one shared config template. PHP 8.3 must be confirmed available in local dev (DDEV/Valet), CI images, and production before the bump — the Composer failure otherwise is immediate and unambiguous, which is the good case.

Sequencing (recommended).

1. Confirm PHP 8.3 availability across CI, local, staging, production.
2. Run the config-drift audit (step 2 above) read-only; quantify exposure.
3. Upgrade one low-traffic site end-to-end as a canary: Acorn v6 → package ^2.0 → env rename → config reconcile.
4. Verify with an actual send over port 465/SSL, not a config dump. Confirm headers and delivery.
5. Roll out remaining sites in batches; freeze mail-related changes during the window.
6. Only after all sites are on v2.0.0, remove MAIL_ENCRYPTION from all secret stores.

Operational Impact

Maintenance. Ongoing cost is low — one dependency, no infrastructure. The material cost is the one-time, fleet-wide env rename plus the permanent obligation to track Laravel's mail-config contract, which has now changed once and should be expected to change again. Budget recurring review effort rather than one-off.

Support. Single-maintainer, small-community project: responsive on targeted bug fixes (this release is a good signal), but not a vendor with an SLA. Mitigation is standard: pin versions, vendor or mirror if the package becomes load-bearing, and keep the config it generates small enough to inline as a fallback. The v1.0.4 branch is likely unmaintained going forward — sites parked there accrue silent risk.

Scaling. Runtime impact is negligible; this does not scale with traffic. The scaling concern is organizational: cost scales with sites × environments × secret stores, not with request volume. A 20-site fleet with 3 environments each is 60 verification points on the env rename, and manual execution will miss some.

Failure modes (ordered by likelihood × impact).

• Silent mail drop. MAIL_ENCRYPTION renamed in .env but the deployed config still expects encryption, or vice versa → no error, no mail on 465. Highest impact; detect with an active send probe, not logs.
• Stale published config. Project-level config/mail.php overrides the fix, so the upgrade appears successful while the original bug persists. Detectable only by file audit or a live send test.
• Composer resolution failure. PHP <8.3 or Acorn ≤5 with a permissive constraint → hard failure at build. Loud and safe, but disruptive if it lands in a deploy pipeline.
• Partial fleet state. Half the environments renamed, half not; works in staging, fails in production. This is the realistic bad outcome and argues for batching with an explicit completion checklist.

Ramp-up. Low for engineers — the change is an env rename plus a Composer bump, both familiar. The real ramp-up is procedural: whoever owns environments and secrets needs to understand why the rename cannot be skipped and why a green build does not prove mail works. One runbook page plus a mandatory post-deploy send test is sufficient; without the send test, expect at least one silent-downtime incident.