Filament Shiplog Laravel Package

Getting Started

Confirm the stack before you composer require anything. The package targets Laravel + Filament v5 specifically, plus Blade/Tailwind (with Alpine implied by the animation layer). If the app is on Filament v4 or the frontend is an SPA, stop — the integration surface doesn't exist and you'd be reimplementing, not adopting.

Pin, don't float. Pre-1.0, one maintainer, zero dependents, and a release history that already includes a rendering regression. Lock the exact version and the Filament minor at the same time:

composer require ysfkaya/filament-shiplog:0.2.0

Do not adopt 0.1.x. v0.2.0 fixed two things you will otherwise spend an afternoon debugging: a light-text-on-light-page bug under OS dark mode (#1), and <x-shiplog> not forwarding attributes — meaning the documented theme override silently did nothing. Use >=0.2.0 as the floor.

Where to look first, in this order:

1. vendor/ysfkaya/filament-shiplog/src/ — the service provider and the Filament page class. This tells you the namespace, the plugin registration shape, and (critically) whether the page has canAccess() / shouldRegisterNavigation() gating.
2. vendor/ysfkaya/filament-shiplog/resources/views/ — the <x-shiplog> / <ship-log> components and how they expect entries to be passed. The package is a renderer; the view is the contract.
3. composer.json → extra.laravel.providers and the publish tags. Then run php artisan vendor:publish (interactively, or with --provider=) to see exactly which config, views, or migrations exist. Don't guess the tags.

Register in the panel provider — typical Filament plugin shape, adjust to what src/ actually exposes:

public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->path('admin')
        ->plugin(\Ysfkaya\ShipLog\ShipLogPlugin::make());
}

First use case: the internal panel, not the public site. Wire the page into your admin panel with five or six hand-written entries and look at it. That validates registration, theming, and animation with zero exposure risk. Only after that should you consider putting <x-shiplog> on a page clients can reach.

First real decision, before any code: where the entries live. The package dictates presentation, not content. Pick one source of truth — inline config array, a changelog/ directory of markdown files in the repo, or a DB table — and commit to it. Files-in-repo is the right default: it goes through PR review, ships with the deploy, needs no migration, and keeps the data portable if you ever swap the renderer.

Implementation Patterns

Pattern 1 — repo-backed markdown, one file per release. changelog/v1.4.0.md with frontmatter for version and date, body in Keep-a-Changelog sections (Added / Changed / Fixed / Deprecated). A tiny loader (glob + Str::between or a frontmatter parser) builds the array the component expects. This is the pattern that ages best: the changelog moves with the code, git log -- changelog/ tells you who shipped what, and a missing entry becomes a review comment rather than a forgotten admin form.

Pattern 2 — two sources, one renderer. Keep an internal log (all entries, including infra and internal-only changes) and a public log (curated subset) as separate files or directories, and feed each to its own placement. The package does not appear to ship authorization or draft-state handling, so isolating by data source is the only reliable way to prevent leakage. Never filter a combined list with a flag at render time; the flag will eventually be wrong.

Pattern 3 — panel page gated explicitly. Regardless of what the page class does by default, wrap access:

// in the page class, via a small subclass if the property isn't exposed
public static function canAccess(): bool
{
    return auth()->user()?->can('viewChangelog') ?? false;
}

If it's client-facing, also confirm the panel's tenant scoping. Verify by logging in as the lowest-privilege role and hitting the URL directly.

Pattern 4 — public placement behind a route + cache. Render the component inside your own controller/Blade view so you control the URL, middleware, and caching. The timeline is static output; cache it and bust on deploy. That also gives you a single place to swap the renderer later:

{{-- resources/views/changelog.blade.php --}}
<x-shiplog :entries="$entries" theme="class" />

Pattern 5 — the CI smoke test. This is the highest-value thing you can add, given the maturity. A test that renders the page and the component turns an upstream surprise into a red build instead of a production bug:

it('renders the changelog page', function () {
    $this->actingAs(User::factory()->create())
        ->get('/admin/changelog')
        ->assertOk()
        ->assertSee('v1.4.0');
});

Pattern 6 — upgrade as a deliberate act. Pin the version, read the diff on every bump (git log/compare view — v0.2.0 is small and readable), then run the smoke test across the theme matrix below. Do not let this float on composer update.

Theme matrix — test all four states before exposing anything publicly:

Inside a Filament panel you're fine: Filament's dark-mode toggle sets the dark class on <html>, so theme="class" aligns with the host. Outside the panel — a marketing or client frontend — your own toggle must also write the class. If your site resolves prefers-color-scheme purely in CSS media queries, add a small inline script that maps the media query to the class on load and on change.

Gotchas and Tips

The package metadata is wrong. The vendor description talks about shipment/carrier tracking. The code renders a changelog timeline. Ignore the description everywhere it appears — in search results, in procurement docs, in your own issue tracker — or someone will request "carrier integration" for a release-notes widget.

0.1.x is a trap. The documented theme API didn't work (attributes weren't forwarded) and dark mode was broken under OS preference. If you read an old blog post or the README at a stale tag and something "doesn't do anything," check the installed version first.

theme="class" follows only the class, never the media query. This is the single most likely repeat of the v0.1.x bug class under a new configuration. Test with DevTools' "emulate prefers-color-scheme" and by toggling your site's own class, separately.

Style bleed is unproven. Tailwind preflight, base typography, and animation keyframes from the package can collide with the host design system. Scope the component in a wrapper, check the animation under prefers-reduced-motion, and eyeball it next to neighboring content on both a dense admin page and a sparse marketing page.

Content exposure is the risk most likely to become an incident, not a bug. There's no evidence of policy gating on the Filament page or draft suppression on the component. Both are yours to add. Before anything client-facing: log in as a low-privilege user, hit the page URL, view source, and grep for an internal-only string you planted.

Unbounded lists become long DOMs. Rendering every release since 2020 is fine in year one and ugly in year four. Limit the collection to the last N releases, or plan a "load more" from the start.

No editorial workflow, no localization, no RSS, no scheduling. Don't discover this after you've promised it. Authoring conventions live in your repo docs, and per-locale output means per-locale entries filtered by locale — the package won't do it for you.

Bus factor of one, zero dependents, community-only support. The realistic operating model is "vendor it and be prepared to own it." The good news: the codebase is small. Keep the renderer behind a one-file seam — the Blade partial from Pattern 4 — so swapping in a plain hand-rolled timeline is an hour's work, not a project. If the fork becomes permanent, you'll want to have already decided that on purpose.

Debugging checklist when blank or wrong output: confirm the entry payload matches what the view expects; php artisan view:clear and config:clear after publishing; check whether a published view is shadowing the package view (a common cause of "the upgrade did nothing"); and confirm the component namespace is registered if it's not auto-discovered.