Filament Composer Release Notifier Laravel Package

Getting Started

Install the plugin with Composer into an existing Laravel + Filament application:

composer require mominalzaraa/filament-composer-release-notifier

Register the plugin on the panel(s) where you want the version-drift UI to appear — typically app/Providers/Filament/AdminPanelProvider.php:

use MominAlZaraa\ComposerReleaseNotifier\ComposerReleaseNotifierPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugin(ComposerReleaseNotifierPlugin::make());
}

Publish the config so you can tune cache TTL, GitHub token, and mail recipients:

php artisan vendor:publish --tag="composer-release-notifier-config"

If the plugin ships migrations (check vendor/.../database/migrations), run php artisan migrate. Then open the Filament dashboard — the widget reads composer.lock from the project root, queries Packagist/GitHub for each package's latest release, and lists anything behind.

First use case: land on the dashboard, look at the widget card, and scan for packages that are behind. Click through to the resource for the per-package breakdown (current version vs latest, release URL). Nothing writes to your composer.json — this is a read-only observability tool.

The single fastest sanity check after install is: does the widget render at all? If it's blank, that's almost always a missing GitHub token (rate limit) or an unreadable composer.lock path — see Gotchas.

Implementation Patterns

Registering on multiple panels. Register the plugin in each PanelProvider where it's relevant (e.g. admin and a separate "ops" panel). The widget reads the same lock file regardless of panel; only the UI surface differs.

Cache-first reads in your own code. The plugin already caches remote lookups. If you need the same data elsewhere (a CLI command, a slack notification), go through the plugin's service/manager rather than hitting GitHub directly — otherwise you duplicate API calls and burn rate limit. If the service isn't exposed publicly, wrap it in your own thin service and inject the plugin's cache store.

Scheduled email report. The "optionally emails a summary" feature is designed to be driven from the scheduler, not from a button click. Add an entry to routes/console.php (Laravel 11+) or app/Console/Kernel.php:

Schedule::command('composer-release-notifier:send')->weeklyOn(1, '08:00');

(the exact command name comes from the package's Console directory — check php artisan list | grep composer after install). Point it at a real recipient list in config, and run it behind a queue worker if you're mailing many addresses.

Pairing widget + resource. The dashboard widget is the "is anything behind?" glance; the Filament resource is the drill-down. A common daily pattern is: widget on the main dashboard, resource reachable from the widget via a link (Filament resources usually appear in navigation automatically — verify the navigationGroup/navigationLabel in config so it slots next to your existing ops pages rather than landing at the root).

CI/ops integration. Because the plugin only reports, it pairs well with your existing dependency-update workflow (Dependabot, Renovate, or a scheduled composer update PR job). Use the plugin's report as a human-readable weekly summary, and let the PR bot do the actual bumping. Don't try to make the plugin act as a gate — it's informational.

Gating visibility. If you don't want every admin seeing stale-package data, gate the widget/resource with Filament's canView() / ->visible() using a policy or Gate::define. The plugin doesn't ship an opinionated authorization layer, so do it at the panel/page level.

Gotchas and Tips

GitHub API rate limits are the #1 source of "it stopped working." Unauthenticated requests cap at 60/hour, which you'll blow through on any real composer.lock. Always set a GITHUB_TOKEN (a fine-scoped PAT with public read is enough) in config/composer-release-notifier.php and in .env. Symptom is a widget that renders but shows nothing / errors silently — check storage/logs/laravel.log for 403s.

composer.lock is the source of truth — not composer.json. The plugin reads the lock file to get installed versions and compares against latest releases. If you're in a fresh checkout without composer install having run, or in a Docker image where the lock wasn't copied into the app root, the plugin has nothing to compare. Confirm the lock path resolves relative to base_path().

Private/VCS packages won't resolve. Packagist lookups fail for private packages, and GitHub lookups fail for anything not hosted on GitHub. Expect those to show as "unknown" (or be skipped) — don't treat the widget as complete coverage of your dependency tree.

Cache TTL is your lever, not the cache driver. The plugin caches lookups; tune the TTL in config. Short TTL = fresher data but you hammer GitHub; long TTL = stale but cheap. For most teams, once-a-day is right — set TTL >= your scheduled report interval so you don't double-fetch. To force a refresh (e.g. after a big composer update), clear the plugin's cache namespace rather than cache:clear on the whole app.

The email report needs the scheduler running. A very common "it never emails" is simply that php artisan schedule:work / the cron entry isn't configured. Verify with php artisan schedule:list that the notifier command appears, then php artisan <command> --dry-run (if supported) to confirm it produces a body before trusting the cron.

No auto-update — by design. There is no "bump this package" button. If a stakeholder asks for one, that's a separate feature; the plugin is a read-only informer. Don't hack write access into it; drive updates through Composer in CI.

Extension points. Treat the published config as the primary customization surface (recipients, token, TTL, widget labels). For deeper changes — custom sorting, filtering out dev dependencies, adding a Slack transport — subclass the widget or the mail notification rather than editing vendor code. After upgrading the plugin, re-run vendor:publish --tag=... --force only if you've diffed against your customized config; otherwise you'll clobber it.

Debugging checklist, in order: (1) php artisan about shows the provider loaded? (2) composer.lock present and readable? (3) GITHUB_TOKEN set and not expired? (4) cache not holding an empty result from a prior failed run — flush the plugin cache namespace and retry.