Filament Mail Editor Laravel Package

Technical Evaluation

Architecture fit

• The package is now a two-layer stack: jeffersongoncalves/laravel-mail-editor (models, enums, events, support classes, seeder, config, migrations, translations) plus this Filament plugin (resources, drag-and-drop builder, metrics widget, block forms). This is a sound separation — the domain/persistence layer becomes usable headless (API, queue jobs, console commands, other UIs) and the Filament layer becomes a thinner, replaceable presentation concern.
• For teams already on Filament, the plugin remains the correct integration point; the core package arrives automatically as a transitive dependency, so the install surface is unchanged even though the dependency graph is not.
• The new HasPropsSchema contract is the architecturally significant addition: it turns custom blocks from a "hack the form schema" exercise into a supported extension point. This materially improves fit for teams with bespoke block types (product grids, personalized content, dynamic pricing tables).

Integration feasibility

• Net-new integration is straightforward: one composer require, publish --tag="mail-editor-config" and --tag="mail-editor-migrations", run migrations.
• Upgrades from any pre-1.1.0 install are not drop-in. Four independent breaking axes must be handled in one pass: namespace relocation across app code, config file rename plus key rename, route path and route-name changes, and an export format identifier change. Each is individually small; together they are a coordinated migration with a real chance of a partial cutover.
• The import-compatibility guarantee is one-directional only: filament-mail-editor exports still import into 1.1.0, but 1.1.0 exports will not import into older installs. Any environment fleet running mixed versions (staging on new, prod on old, or a shared template library) will hit asymmetric failures.

Technical risk

• Versioning signal is wrong. Namespace moves, config key renames and route renames are breaking changes under SemVer and warrant 2.0.0. Shipping them as 1.1.0 means ^1.1 constraints will silently pull a breaking release. This is the single highest-severity finding and should drive the pinning strategy regardless of everything else.
• Route relocation is a production-data risk, not just a code risk. Preview and countdown routes moved from /filament-mail-editor/* to /mail-editor/*. If those URLs are embedded in emails already dispatched to recipients (countdown timers and "view in browser" links are exactly the kind of thing that gets emailed), previously sent mail will 404 after deploy. There is no stated redirect or alias.
• Maintainer concentration. The core was extracted into a second repository under the same individual maintainer. Two packages must now stay version-aligned, and the plugin's dependency constraint on the core is not specified in the notes. Coupled releases from a single maintainer increase the chance of an uncoordinated bump breaking installs.
• Verification depth is thin. "Smoke tests for every resource page and custom table actions" is a meaningful improvement in regression coverage for the Filament layer, but smoke tests assert pages render, not that builder output is correct, that preview rendering is faithful across mail clients, or that migrations are reversible from the old schema.

Key questions

1. Is there a redirect/alias or a documented rewrite rule for the old /filament-mail-editor/* routes, and are those routes known to appear in already-sent email?
2. What version constraint does the plugin place on laravel-mail-editor, and is the core's release cadence locked to the plugin's?
3. Was the 1.1.0 version number intentional, or is 2.0.0 planned as a corrective re-tag?
4. Are there upgrade/migration docs and a namespace-rewrite helper, or is the namespace move a manual find-and-replace across app code, published config, and any custom block classes?
5. Does HasPropsSchema have a documented BC policy — is it stable enough to build internal blocks against, or explicitly experimental?
6. Is any state stored in the database keyed by the old export format id or old class names (queued jobs, serialized payloads, stored block type discriminators)?

Integration Approach

Stack fit

• Requires Laravel with Filament; the domain layer is now framework-idiomatic Laravel and no longer requires Filament to be present. That opens a viable path for headless consumers (transactional-send services, template APIs) to use the core without the admin UI.
• Config key, migration tag, translation namespace and route prefix are all unified under mail-editor, which is the right convention and reduces the "which prefix is it this time" cognitive load.

Migration path

1. Pin before doing anything. Constrain the plugin to the exact version you validate rather than floating ^1.1, given the breaking-change-to-version mismatch.
2. Inventory blast radius. Grep the codebase for FilamentMailEditor, filament-mail-editor, filament-mail-editor-migrations, filament-mail-editor-config, and the literal route strings. Also search custom block classes, service providers, factories, seeders and any test fixtures. Enumerate stored data referencing old class names (polymorphic type columns, queued job payloads, serialized form state).
3. Handle routes separately from code. Before deploy, establish redirects from the old preview/countdown paths to the new ones so in-flight email stays functional. This is a config-layer change that can ship ahead of the release upgrade.
4. Rename config first, in isolation. Publish mail-editor-config, diff against the existing filament-mail-editor config, and delete the old file only after confirming no code reads the old key.
5. Run migrations on a restored production copy, not a fresh DB. The interesting question is upgrade-in-place from the prior schema, which smoke tests almost certainly do not cover.
6. Rewrite namespaces last, as a mechanical pass, with static analysis (PHPStan/Psalm) or a full test run as the gate — a partially rewritten namespace produces "class not found" errors that unit tests usually catch but runtime-only paths (queued jobs, scheduled commands) often do not.
7. Freeze the export format boundary. Ensure template libraries are re-exported in the new format after cutover, while retaining old exports for one release cycle.

Compatibility

• Import is backward compatible (old format id still imports); export is not forward compatible. Treat template libraries as versioned artifacts and store them alongside the package version that produced them.
• Mixed-version fleets are the primary hazard: define one canonical version per environment and roll them in the same window, or a template authored on staging will be un-importable on production.
• Third-party custom blocks built against the old namespace will break at class-load, not at render — plan for a coordinated update of any in-house extensions.

Sequencing

• Ship route redirects first (independent, reversible, protects live email).
• Then upgrade the package with config + namespace changes in a single PR, deploy to staging, and exercise the builder, preview, countdown, metrics widget and seeded data.
• Then re-export template libraries and validate import round-trip.
• Adopt HasPropsSchema for custom blocks only after the upgrade is stable — do not bundle a feature adoption into a breaking-change window.

Operational Impact

Maintenance

• Two repositories to track instead of one. Release notes for the plugin will no longer describe the full change surface; a core bump can change behavior with no entry in this changelog. Subscribe to releases for both, and treat the plugin's composer constraint on the core as part of your review surface.
• The unified mail-editor config/migration/translation prefix reduces long-term drift and makes future config diffs easier to reason about.

Support

• First-line support burden shifts toward upgrade breakage rather than defects. Expect a spike in "preview link 404" and "class not found" tickets during rollout; publish an internal runbook with the grep commands and redirect map before the upgrade window.
• Backward-compatible import is a real support win — users with saved templates will not lose them, which removes the most common escalation from a format change.

Scaling

• The split does not change runtime scaling characteristics of the Filament admin (still one app-server workload). It does unlock horizontal separation later: the core can run in a worker/API tier without dragging the admin UI along.
• The metrics widget remains the notable scaling consideration — it queries the core's tables, so review its query patterns against production data volume before enabling it broadly.

Failure modes

• Silent route breakage: sent emails with old preview/countdown URLs 404. Highest user-visible impact, lowest detection probability in tests.
• Partial namespace migration: runtime-only failures in queued jobs or scheduled tasks that no page smoke test exercises.
• Mixed-version template library: asymmetric import failure between environments.
• Unpinned transitive core bump: composer update pulls an incompatible core under a plugin patch release.
• Stale published config: old config file retained alongside the new one, silently ignored, causing confusing behavior differences between environments.

Ramp-up

• Low for the core concepts — the public API surface is Filament resources and a builder UI, and HasPropsSchema is a single-contract learning cost for teams writing custom blocks.
• Moderate for the upgrade itself. Budget roughly a half-day for a small codebase with no custom blocks, and 2–3 days for a team with in-house blocks, a template library, and queued mail. Allocate the higher end where preview/countdown links are already in the wild.
• Add one-time effort to document the effective config surface post-rename; contributors will otherwise reference the old filament-mail-editor key from memory and prior documentation.