Supervisor Laravel Package

Getting Started

Install via Composer and publish the package's config in one pass:

composer require tanwencn/supervisor
php artisan vendor:publish --provider="Tanwencn\Supervisor\SupervisorServiceProvider"

The first place to look is config/supervisor.php after publishing — this package is a thin behavior-recording utility, so essentially everything it does is driven by that config (storage target, channels, formatting). If the config doesn't publish cleanly, open vendor/tanwencn/supervisor/src and inspect the service provider's register()/boot() to see what it actually binds — at 10 stars and a 2021 release, docs are lean and the source is the real README.

Your first use case is almost always replacing scattered Log::info('user did X') calls or ad-hoc DB audit rows with a single supervisor entry point. Once installed you should be able to record an event from anywhere in the app — a controller, a queued job, a model observer — and have it land in the configured sink. Verify this end-to-end before wiring anything else: record one event, confirm where it appears, then delete the test artifact.

A quick sanity check that it's wired up:

use Tanwencn\Supervisor\Facades\Supervisor;

Supervisor::record('user.login', ['user_id' => auth()->id()]);

If the facade alias isn't registered, add it to config/app.php under aliases or use the fully-qualified class. Confirm the Laravel version constraint in composer.json matches your app — a 2021 package most likely targets Laravel 8, and running it on 10/11 may need --ignore-platform-reqs at install time and a manual smoke test afterwards.

Implementation Patterns

Single choke point for behavior events. Rather than sprinkling supervisor calls everywhere, introduce one small application-level helper or a RecordsBehavior trait so your domain code depends on your own interface, not the vendor package. If the package is abandoned (it hasn't shipped since Aug 2021), swapping it out becomes a one-class change instead of a grep-and-replace across the codebase.

trait RecordsBehavior
{
    protected function record(string $event, array $context = []): void
    {
        Supervisor::record($event, $context);
    }
}

Observer-driven recording. The natural fit for a "monitor any behavior" utility is Eloquent events — attach recording to created/updated/deleted in observers so you get an audit trail without touching every controller. Keep the context payload to scalar primitives (id, changed keys, actor id) rather than dumping whole models; serializing full models is where these utilities turn into a performance and storage problem.

Wrap in a queued listener for hot paths. If the sink is a database or remote channel, recording inline in a request adds latency and creates a failure mode (supervisor down = request fails). Push recording to a ShouldQueue listener so a broken sink can never take down the user-facing path.

Pair with middleware for request-level context. A tiny middleware that records request.start/request.end with route, status, and duration gives you monitoring with zero per-endpoint code. Combine with the observer pattern above and you cover both "what changed in the data" and "what the app did."

Treat it as the source for dashboards, not the dashboard. Use the recorded events to feed whatever you actually visualize (a simple DB query, an admin page, or an external tool). Don't expect the package itself to render anything — it's a recorder, so build a read model on top.

Gotchas and Tips

• Abandonment risk is the headline gotcha. Last release 2021-08-20, 10 stars, MIT. Pin the exact version in composer.json, commit composer.lock, and treat any update as a manual review — there won't be a security patch. Have a migration plan to a maintained alternative (Laravel's own event/listener system, spatie/laravel-activitylog, or a plain logging channel) if your use case outgrows it.

• Config publish is the debug lever. Most "it doesn't record anything" issues trace to the config not being published, or to a storage target (path, connection, table) that doesn't exist. After publishing, check that the target is writable/reachable before blaming the code.

• Check the provider and alias registration. Older Laravel package-discovery works, but if you're on a Laravel version after the package's era, verify Tanwencn\Supervisor\SupervisorServiceProvider is actually in bootstrap/providers.php / config/app.php. A missing alias is a Class not found error that looks scarier than it is.

• Version constraints will bite on Laravel 10/11. Install may fail on illuminate/support bounds. Don't blindly --ignore-platform-reqs — install into a throwaway branch, run your test suite, and specifically exercise the recording path, since the internals may call APIs that shifted.

• Keep context payloads small and serializable. Whatever the sink is (file, DB, log channel), large arrays or model instances will either bloat storage or fail serialization. Sanitize to IDs and scalars, and never put credentials/PII in a behavior record.

• Wrap calls defensively in critical paths. If recording throws, it can break the request. Guard non-essential recording in a try/catch or, better, route it through a queue so failures are contained.

• Extension point is the config + facade, not a plugin system. At this size there's no event bus or driver architecture to hook into. If you need custom sinks, you'll be extending/replacing the service provider or wrapping the facade in your own abstraction — which is another reason to build that thin wrapper from day one.