Resource Watcher Laravel Package

Getting Started

• Install the package with Composer and publish any config/service-provider assets it exposes. If Laravel auto-discovery is enabled, no manual provider registration is usually needed.
• Look first at the published config file (if any), the listener class/facade, and the package tests. The v1.1.0 release notes point to two things to verify immediately: the new fluent API and the listener callback signature.
• First use case: register one broad listener, log every change, and confirm the wiring before adding filters. This is the quickest way to validate anything() and the new $resource, $absolutePath callback contract.

use Illuminate\Support\Facades\Log;

// Register the listener for any change.
$listener->anything();

// Callback shape in v1.1.0:
// first parameter: the resource
// second parameter: the absolute path
function ($resource, string $absolutePath): void {
    Log::info('Resource changed', [
        'resource' => $resource,
        'path' => $absolutePath,
    ]);
}

Use the package’s actual callback-registration method where applicable; the important part is that v1.1.0 adds anything() and standardises callbacks as resource-first, absolute-path-second.

Implementation Patterns

• Use anything() for audit-style listeners where you need to know that something changed, then branch on $resource inside the callback. For high-volume paths, prefer narrower listeners and reserve anything() for low-traffic directories or debugging.
• Keep callbacks thin. Dispatch a Laravel event, queue a job, or call a small action class from the callback. Avoid running file operations, HTTP calls, or expensive scans inline.
• Prefer a dedicated listener class per domain/module. Register it in AppServiceProvider::boot() or a package-specific provider, and gate registration behind config or environment checks.
• Use the new callback signature intentionally: $resource for domain logic and $absolutePath for logging, deduplication, and file-system operations. Avoid recomputing the path from the resource when the absolute path is already supplied.
• Forward changes into Laravel jobs/events from the callback:

// Inside your listener callback:
ProcessResourceChange::dispatch($resource, $absolutePath);

• In tests, assert both callback parameters. Use a temporary directory and absolute paths so assertions match production behavior. Add one test that proves anything() catches multiple change types, not just the one you normally use.
• When upgrading, keep existing listeners behind an adapter only if you are unsure about the old callback argument order:

$callback = function ($resource, string $absolutePath) use ($oldHandler) {
    $oldHandler($absolutePath, $resource);
};

Only use an adapter if your old handler expected a different signature; otherwise migrate directly to the v1.1.0 signature.

Gotchas and Tips

• Callback argument order is the main upgrade risk. v1.1.0 says callbacks receive $resource first and $absolutePath second. A closure that previously expected a string path as the first argument may now receive a resource object and fail with a TypeError when invoked. Audit every listener callback after upgrading, even though the release is marked backwards compatible.
• anything() can be noisy. It listens for any change, so filter early by resource type or path prefix. Otherwise you may process lock files, temp files, or unrelated writes.
• Absolute paths are not normalized for you. Expect platform differences: Windows separators, symlinks, trailing slashes. Normalize before comparing paths, and log the absolute path exactly as supplied when debugging.
• Fluent chains need a terminal action. If the new fluent API requires a final registration/execution call, an incomplete chain may silently do nothing. Confirm the listener is actually registered in a test or with a debug log.
• Clear config cache after publishing config. In Laravel, php artisan config:cache can hide new config keys. Run php artisan config:clear locally and redeploy cached config in production.
• Be careful with queued listeners. If a callback is queued, the $resource value must be serializable. If it is not, pass a stable identifier or path and resolve the resource inside the job.
• Debug with both parameters. Log $resource and $absolutePath together at debug level. When a callback does not fire, verify listener registration first, then the path/filter, then the callback signature.
• Extension points: prefer package config, custom listener classes, and Laravel events/jobs over editing vendor code. The listener callback is the safest day-to-day extension point for custom behaviour.