Filament Knowledge Base Laravel Package

Getting Started

• Require the plugin alongside jeffersongoncalves/laravel-knowledge-base ^2.0. The 1.3.1 release is explicitly tested against that core line, so pin the core accordingly before upgrading.
• Register the plugin on the Filament panel(s) where articles should be managed — typically an admin panel for authoring, and the Guest/User panels for reading. The release notes confirm both Guest and User panels resolve article content before rendering.
• Run the core install/publish steps (config, migrations, assets). You only need php artisan storage:link if you are on an older core version that links directly to the public disk; with core ^2.0 the asset layer serves through ArticleAssets::url() instead.
• Pick your asset disk strategy up front. 1.3.1 makes the editor write attachments with private visibility, so plan for private storage (e.g. a non-public disk) rather than assuming public.
• First use case: create an article in the admin panel, attach an image through the editor, then view it from the Guest or User panel. That exercises the whole path — private disk, signed URL generation, and content resolution — that 1.3.1 fixes.

Implementation Patterns

• Always resolve URLs through the core, not the disk. Use ArticleAssets::url() (directly or via the asset manager/editor) rather than Storage::disk(...)->url(). This is what gives signed URLs for non-public articles and keeps thumbnails working on a private disk.
• Let the editor own attachment persistence. File attachments are stored with private visibility by the plugin. Avoid overriding the disk visibility in your own form callbacks unless you also replicate the URL-refresh behaviour.
• Rely on load-time URL refresh for stale editor state. The editor refreshes asset URLs when the form loads, including Trix attachment data. This is what keeps images visible when a stored URL has expired — don't cache the rendered Trix HTML with embedded absolute URLs and expect it to keep working.
• Match assets by UUID when reconciling. 1.3.1 recognises images by asset UUID in core-served URLs, not just by disk path, so images get their asset id assigned on save. If you have custom save hooks that parse image URLs, parse the core URL/uuid rather than reconstructing a disk path.
• Handle missing assets gracefully. The Guest/User panels now omit deleted images from resolved content. Don't add your own hard failure on a missing asset; treat omission as the expected contract.
• Panel separation. Authoring (admin) uses the editor and asset manager; Guest/User panels are read-only renderers. Keep any custom article rendering going through the core's content resolution so signed URLs and deletions are handled consistently.
• Testing. In feature tests, assert on resolved content through the panel/controller rather than raw HTML, and use Storage::fake() with a private-visibility disk to reproduce signed-URL behaviour.

Gotchas and Tips

• Signed URLs expire. That's the point of the fix, but it means any URL you persist outside the editor (emails, exports, cached fragments) will go stale. Re-resolve via ArticleAssets::url() at render time.
• Private visibility is now the default for editor attachments. If you previously relied on public disk URLs, upgrade checks should verify image rendering in the Guest and User panels, not just in the admin editor.
• storage:link is conditionally unnecessary. It's only required with core versions that link straight to the public disk. Adding it on ^2.0 is harmless but won't fix broken images — check the signed URL path instead.
• Filament 3 backport. 1.3.1 is a backport of #64 to Filament 3. If you're on Filament 4, confirm you're on the matching release line rather than assuming this changelog applies.
• Debugging broken images: check (1) disk visibility, (2) whether the URL came from ArticleAssets::url() or a disk URL, (3) whether the stored URL has expired and the form has reloaded, (4) whether the asset was deleted (expected omission), and (5) whether the URL contains a core asset UUID for save-time reconciliation.
• Trix attachment data is a separate surface. If images show in the editor preview but not after save/reload, inspect the Trix attachment payload — the load-time refresh covers it, but custom JS that rewrites attachments can bypass that.
• Extension point: keep customisations in form/table callbacks and content renderers that consume the core's resolved output; avoid forking the asset URL logic, as the private-disk behaviour is centralised there.