Communication Laravel Package

Getting Started

This package handles outbound mail plus the settings that surround it: mail senders (the SMTP/transport configs formerly stored as "SMTP settings"), a log of delivered mail (sent-mails), and marketing/communication settings. v0.5.0 is a schema-consolidation release, so the very first thing to establish is whether you are on a fresh install or an upgrade.

Fresh install

1. composer require the package, then publish config and migrations.
2. php artisan migrate — you now get 3 migrations instead of 9. Read the create migrations first: with the upgrade-only migrations gone, they are the single source of truth for the final schema (tables, columns, indexes, foreign keys).
3. Seed or create one mail sender, point it at your transport (log driver locally), and send a test mail.
4. Confirm the message appears in the sent-mail log and that the detail view renders — that round trip exercises sender resolution, transport, logging, and routing in one go.

Upgrading an existing install

Do not jump straight to 0.5.0. Install v0.4.12 first, run php artisan migrate, then upgrade to 0.5.0. The create migrations keep their original file names, so after the upgrade migrate is a no-op — which is the intended behaviour, not a bug.

Where to look first: README for the current class/route names (the release notes describe concepts — mail senders, sent-mails, marketing-settings, communication-settings — not exact namespaces), then the 3 create migrations, then config/ for the mailer and route-prefix options.

Best first use case: replace hand-rolled SMTP config in config/mail.php with a package-managed mail sender, then send a transactional mail through it. That is the smallest change that proves the package is wired correctly.

Implementation Patterns

Sender resolution instead of static SMTP config. The move from "SMTP settings" to "mail senders" implies a first-class model you can have several of. The pattern that pays off: create named senders (transactional, marketing, per-tenant), then resolve the right one at send time rather than editing .env. Wrap resolution in a small service so a future sender-type change is one file, not a grep.

Log-then-list. Send through the package's mailer so every message is persisted to the sent-mails table, then build admin screens on the package's list/detail views (or your own querying the same table). Resist adding a second logging layer — you will get duplicate rows and disagreeing timestamps.

Settings as a resolution layer. Marketing and communication settings are almost certainly key/value with defaults. Resolve them through one accessor and cache the result per request (or per tenant); reading settings inline at every call site makes later schema changes painful and scatters caching bugs.

Deployment pipeline split. Keep two CI lanes: a fresh migrate from zero (proves the consolidated schema is valid) and an upgrade lane that installs 0.4.12, migrates, then upgrades. The upgrade lane is the only thing that catches "this migration was deleted but my production DB needed it". A RefreshDatabase suite now runs 3 migrations, so tests are cheap — lean on that.

Integration points. If your app sends mail from queued jobs, terminate sender selection before dispatch and pass an identifier, not an Eloquent model — the sender row can change between enqueue and run. For multi-tenant apps, check whether senders/settings are globally scoped; if they are not tenant-aware in the schema, wrap access in a scope rather than forking the package.

Gotchas and Tips

The upgrade path is mandatory, not advisory. Going from 0.4.11 or earlier directly to 0.5.0 leaves you with a schema the create migrations describe but your database does not have, because the create migrations are already recorded as run. 0.4.12 is the bridge — make it a hard step in your runbook, not a suggestion.

Removed upgrade-only migrations mean removed cleanup. The marketing rename, the SMTP→mail senders move, and the column drops no longer exist. On an existing database the old columns will simply persist forever. If you care about dead columns (nullable smtp_* leftovers, the pre-rename marketing table), write your own one-off cleanup migration after upgrading — and back up first, because dropColumn on a table you have not inspected is the classic way to lose data on a driver where it rebuilds the table.

Legacy 301s are gone. /sent-mails, /sent-mail/{id}, /marketing-settings, /communication-settings no longer redirect. Anything hardcoded — old admin links in emails, browser bookmarks, internal docs, route() calls in Blade, snapshot tests asserting a redirect — silently becomes a 404. Grep the codebase for those four strings and for the old route names before you deploy.

Published migrations: filenames now matter. Because nothing re-runs after upgrade, a published-and-edited create migration will diverge from upstream forever. Avoid editing them in place; add a new migration for your changes. If you already edited one, diff it against the 0.5.0 original before upgrading.

Debugging checklist. php artisan migrate:status to confirm all 3 are recorded; php artisan schema:dump or SHOW CREATE TABLE on the sent-mails table to compare reality against the create migration; check that settings rows were actually transformed if you upgraded through 0.4.12 (the rename migration is gone from 0.5.0, so it must have run before you upgraded).

Extension points. Config publishing for route prefix and middleware is the safe seam — use it for auth-gating the admin screens rather than editing package routes. Avoid subclassing the mailer unless the README documents it; sender resolution and logging are the two things most likely to change shape in a 0.x package. Pin the version ("^0.5" with a committed lockfile) — on 0.x, minor bumps have already shipped one breaking change.