Filament Advanced Rich Editor Laravel Package

Getting Started

• Confirm the stack first. This is a Filament v5 package. Check your app's composer.json, then confirm the package's own constraints before installing. The v1.7.0 notes include a fix aimed squarely at Filament 5.10 (toolbar pickers rendering in the bar instead of over the text), so pin both your Filament minor and this package's version together — a mismatch here presents as a visual bug, not an install error.
• Install into a disposable branch or scratch panel first. Still a young, low-adoption package (11 stars, zero dependents). Treat the first install as a spike rather than a production rollout.
• Run php artisan filament:assets after install and after every update. As of v1.7.0 the stylesheet is split in two: filament-advanced-rich-editor.css loads on every panel page, and filament-advanced-rich-editor-overlays.css is pulled in by the editor via x-load-css when it starts. If you skip asset publishing, the first sheet works and the second is missing — pickers, menus, the media browser, find/replace and dialogs render unstyled. That looks exactly like a broken editor and is not one.
• Publish and inspect config. Publishing the config is still the right move, but note it is now a recurring task: a published config file does not receive new keys on upgrade. v1.7.0 adds description_list (plus a fourth lists entry) and invisibles (plus two tools_menu entries). Re-publish into a temp location and diff rather than overwriting:

  php artisan vendor:publish --tag=filament-advanced-rich-editor-config
  php artisan filament:assets
  php artisan optimize:clear
  

  Verify the exact publish tags in the README or service provider before relying on them.
• Read the package source as documentation. The README and release notes remain the primary docs; the config file, field class, resources/lang folder, and now the JS entry points (menu-position.js, image-panel.js, color-picker.js, font-size-picker.js) are the practical references.
• First use case: replace one existing RichEditor in a scratch Resource form. Keep the old field in place until you have tested create, edit, save, reload, and frontend rendering.
• Smoke-test in this order:
  1. Field renders and saves HTML.
  2. Toolbar can be arranged per field, and dropdowns open over the text on your exact Filament version.
  3. Slash menu, callouts, find/replace, accessibility check, browser drafts, and the new invisibles/blocks toggles work in the browser (the invisibles script is new — if it 404s, your assets are stale).
  4. Spatie Media Library attachments work only after the core editor is stable.
  5. Deletion/replacement flows are tested last, on staging data only.

Implementation Patterns

• Use it as a field-level replacement, not a global fork. Swap RichEditor::make('content') for the package field only where the extra authoring features are worth the dependency.
• Centralize toolbar definitions. Put common toolbars in a helper or custom field factory so upgrades to the toolbar API touch one file:

  // Illustrative only — verify the exact class and method names in the package source.
  AdvancedRichEditor::make('content')
      ->toolbar(['bold', 'italic', 'link', 'callout', 'media'])
      ->columnSpanFull();
  

• Switch definition lists on deliberately. v1.7.0 adds <dl>/<dt>/<dd> for glossaries. It is off by default for good reason: enabling it over a run of existing paragraphs converts every other one into a term. Turn it on per field with ->descriptionList() — and note "switching it on over a run of paragraphs" is a mutation, so never enable it on a field with live content without exporting first. Stored definition lists render whether or not the feature is enabled on the field, so output styling is safe to adopt ahead of input.
• Treat the invisibles/blocks toggles as authoring aids, not data. Show-invisible-characters and show-blocks change nothing that is stored — saved HTML, clipboard and undo history are identical with them on or off, and both reset to off on page load. Safe to leave enabled in tools_menu; useless (and confusing) as a QA gate, since nothing persists.
• Use the media browser as an editorial workflow. The media browser, Spatie Media Library attachments, and replace/delete actions are the highest-value and highest-risk features. Define who may delete or replace shared files using the package's authorization closures/config values, and test with a non-admin account.
• Be explicit about media documents. The package infers the field's own column; any other model or column should be named via ->mediaLibraryDocuments() or media_library.documents. In multi-model apps, configure deliberately.
• Use custom media sources as the extension seam. Implement the MediaSource contract and, for replacement, ReplacesMedia, rather than patching the media browser.
• Localize with your eyes open. v1.7.0 ships ten new locales (cs, da, nl, fr, it, nb, pl, pt_BR, es, sv) beside en and de. They are AI-translated and parity-tested against English, but only English and German have been read by a native speaker. For editor-facing UI in a client's language, budget for a review pass and submit corrections upstream; missing lines fail back to English silently, so a partial locale looks fine until an editor hits an untranslated menu.
• Design for HTML output early. Confirm how the field stores content and how your frontend renders it. Sanitize or transform rich HTML consistently for callouts, media cards, embeds, videos, and the new definition lists. Test the same content in the editor and on the public page.
• Roll out behind a flag or with a dual field. Keep the old editor path until round-tripping is verified; rich text corrupts silently.
• Scale-test in a repeater, not in isolation. v1.7.0 specifically targets pages with many editors (server render, first-frame, long tasks, markup weight). If your use case is "one article field", these wins are mostly irrelevant; if it is a repeater of ten or twenty editors, measure before and after on your own hardware rather than trusting the published numbers.

Gotchas and Tips

• This is still a low-adoption package. Eleven stars and zero dependents means fewer community answers and a higher chance edge cases are undocumented. Pin the exact version, review every changelog entry, test upgrades on staging.
• Asset staleness is now the single most likely "bug" you will file. The overlay stylesheet, menu-position.js, image-panel.js, color-picker.js, font-size-picker.js and the invisibles script are all new or newly extracted. Any of them missing produces a plausible-looking failure (unstyled picker, misplaced dropdown, missing toolbar affordance). Before debugging anything, run php artisan filament:assets and hard-reload with browser cache disabled. Add it to your deploy script and to your upgrade checklist.
• Published config drifts on every feature release. v1.7.0 is a concrete example: new description_list and invisibles keys plus new menu entries that only arrive if you re-publish. Diff, don't overwrite — you will otherwise lose your customized tools_menu and lists.
• Media replacement is powerful and destructive-adjacent. Replacing a shared file rewrites every entry that uses it. Back up tables and storage, run the flow on staging, and verify sized images, conversions, card names, and document trees.
• Deletion/replacement rewrites stored content through models. On large content sets this may be slow or may touch model events, observers, and revision systems. Check whether the save path bypasses your application's content pipeline.
• Confirm document-column discovery. If content lives in a JSON column, custom model, or block structure, configure mediaLibraryDocuments() explicitly. Silent misses are harder to debug than an upfront error.
• Browser drafts are browser-local. Not shared across devices, users, or sessions. Clear browser storage during testing so stale drafts don't mask save failures.
• Find/replace operates on rich content. Replacing text inside HTML can match markup, attributes, or serialized JSON. Test around links, callouts, embeds, and media cards before letting editors loose. The slash menu is now accent- and case-insensitive (/enum finds énumération), so command aliases you expose to users should be checked for accidental collisions — ø, æ, ł and ß remain distinct letters.
• The accessibility check is advisory. It won't catch everything and does not replace semantic markup, heading structure, alt text review, or a real audit.
• Config and translations can drift. After config edits run php artisan config:clear; cached config hides changes in production-like environments. For a new locale, follow the translation test conventions in CONTRIBUTING.md.
• Custom theme or CSS overrides: rebase onto the split stylesheet. Overlay rules moved to the second sheet. The package places it immediately after the main sheet and ahead of the panel's theme, so a theme rule still wins — but a project stylesheet that targeted picker markup by load order or specificity may now be inconsistent. Re-check custom CSS against both files rather than assuming nothing moved.
• Don't reach into picker internals. The colour picker, font size field, image panels, emoji and character pickers are Alpine components with their data attributes (data-arte-emoji, data-arte-characters) written once per editor. If you extended them by string-matching PHP output or duplicating x-data scripts, that code is gone in this release. The supported seam is calling openEmojiPicker() / openCharacterPicker() from your own button with the second argument.
• CharacterCount::measuredBy() is the new hook for expensive counters. The closure runs lazily, the first time the numbers are read — not on every form walk. Good for a custom counter that queries something; don't assume it fires eagerly, and don't put side effects in it.
• Debug in layers. Disable media library integration, then optional toolbar tools, then test a bare field. Watch the browser console for asset/JS errors, the network tab for 404s on the new JS/CSS files and media endpoints, and storage/logs/laravel.log for server-side failures. CSP is now a bigger factor: x-load-css / x-load-src fetch assets at runtime, so a policy that allows only eagerly-loaded assets will break overlays while the base editor still looks fine.
• Inspect extension points before forking. MediaSource, ReplacesMedia, config closures, per-field methods, and CharacterCount::measuredBy() are the intended surface. Prefer them over patching vendor code so upgrades stay possible.
• Bottom line: v1.7.0 is a substantial performance and ergonomics release — worth taking if you run editor-heavy repeaters, and the definition-list and invisibles features are genuinely useful for editorial fields. It is still not a "set and forget" dependency: pin the version, run php artisan filament:assets on every deploy and after every update, diff your published config on each upgrade, review the unreviewed locales, test media deletion/replacement aggressively, and keep a plain Filament RichEditor fallback until the package has more production mileage.