telkins/laravel-watchable
Laravel Watchable adds watch and unwatch capabilities to your Eloquent models, letting users follow records and receive notifications when they change. Simple traits, polymorphic subscriptions, and query scopes make it easy to integrate into any Laravel app.
v0.2.0 is a compatibility release, not a feature release: the only added capability is Laravel 8 support. There is no new public API to learn, so "getting started" is mostly about deciding whether and where to install it.
Before you install anything:
composer.json in the package repo first, not the README. In a release whose headline is framework support, the require block is the real changelog — confirm the illuminate/* constraints now allow ^8.0, and note the minimum PHP version it drags in. Laravel 8 packages commonly require PHP ^7.3|^8.0; if your app is still on 7.2, this release is not installable for you regardless of the framework version.tests/ directory. An experimental package with a one-line changelog tells you very little; the test suite tells you which framework versions are actually exercised in CI versus merely declared in composer.json.First install (deliberately conservative):
composer require --dev vendor/package:0.2.0
php artisan package:discover
Pin the exact version rather than ^0.2. The release note explicitly says "experimental" and "should not be considered production-ready" — a caret constraint on a 0.x package permits 0.3.0, which under semver is allowed to break you.
First use case: pick a single, non-critical, easily reversible integration point — a console command, an artisan-invoked report, or a local/dev-only debugging aid — and drive it end to end there before touching a request path. The goal of the first session is to learn the package's surface area (service provider, config file, facade or helper, any publishable migrations) on ground where a failure costs you nothing.
Where to look first, in order: the auto-discovered service provider (it reveals bindings, singletons, and any mergeConfigFrom/loadMigrationsFrom calls), the published config file, then the README's examples — which are frequently stale relative to the code in 0.x releases.
Isolate it behind your own boundary. This is the single most important pattern for an explicitly experimental dependency. Define a small interface in your app, implement it with the package's API, and bind it in a service provider. When v0.3.0 breaks the signature, you change one adapter class instead of grepping the codebase:
// app/Contracts/Thing.php
interface Thing { public function handle(array $payload): array; }
// app/Providers/AppServiceProvider.php
$this->app->bind(\App\Contracts\Thing::class, \App\Support\PackageThing::class);
This also gives you a trivial fake for tests, which matters more than usual when you cannot trust the package's own test coverage.
Keep it out of serialization boundaries. Do not let package objects, DTOs, or exceptions travel through queued jobs, cached values, or session payloads. An experimental release can change an object's shape between patch versions, and a __serialize mismatch surfaces as a failed job at 3am rather than a compile-time error. Convert to plain arrays or your own value objects at the adapter edge.
Configuration: after installing or upgrading, publish and diff rather than publish and overwrite:
php artisan vendor:publish --provider="Vendor\Package\ServiceProvider" --tag=config
In 0.x, config keys get renamed without deprecation shims. Keep the published file in version control and read the diff on every upgrade — a renamed key usually fails silently back to a default rather than throwing.
Feature-flag the integration. Wrap the call site in a config flag or Laravel Pennant-style toggle so you can disable the package in production without a deploy. Given the explicit non-production-ready warning, you want a kill switch that is one config value, not one revert commit.
Version pinning and CI. Commit composer.lock. Add a CI job that installs the lowest and highest supported Laravel 8 minor versions (8.0 and 8.83 behave differently) plus your actual production PHP version. Experimental packages are disproportionately likely to pass on the author's PHP 8.0 and fail on your 7.3.
Laravel 8 specifics to verify rather than assume: auto-discovery caching (php artisan package:discover after every composer operation), namespaced model factories if the package ships any, and composer require under Composer 2 — if the package's composer.json lacks a "version" field or uses a VCS repository, constraint resolution can behave differently than on Composer 1.
"Experimental" is the headline, not a footnote. Treat the note as the release's most important content. No backwards-compatibility promise, no security-response commitment, and — critically — no statement about whether this release was tested against real Laravel 8 applications or just had its constraint loosened. Verify the CI matrix yourself; a widened constraint is not the same as tested support.
Constraint-only compatibility is a common trap. Many packages "add Laravel 8 support" by editing composer.json and changing nothing else. Look for framework-specific code paths that were actually adapted — Str/Arr helpers, the $namespace property on RouteServiceProvider, the RateLimiter facade, and the container's handling of $this->app in service providers all changed around Laravel 8. If the diff is one line of composer.json, assume the support is nominal and budget time for discovering the gaps yourself.
Upgrade order matters. Upgrade the framework first, confirm the app is green, then add or bump this package. Doing both at once makes attribution impossible when something breaks.
Caches are the usual suspect. After any install, bump, or config publish: php artisan config:clear && php artisan cache:clear && php artisan package:discover. A stale bootstrap/cache/config.php will happily serve old config keys and make you believe a code change had no effect. In production deploys, ensure config:cache runs after the new config file is in place.
Debugging a silent no-op: resolve the binding straight from the container and inspect it, rather than guessing from behaviour:
dd(app(\App\Contracts\Thing::class), config('package'));
If the container returns your adapter but the adapter's underlying package class is a stub or a null object, the problem is configuration, not wiring.
Extension points to prefer: bind against the package's interfaces (if any) rather than extending its concrete classes — protected properties and internal methods are fair game for removal in 0.x. Where the package offers events or a driver/manager pattern, hook there instead of subclassing. Where it offers none, your own adapter plus a decorated wrapper is the durable choice.
Log and observe everything on first rollout. Give the package its own log channel or at least a distinct context key, and add a metric around the call site. When an experimental dependency misbehaves in a way nobody documented, your own telemetry is the only reliable diagnosis path.
Set an explicit review date. Pin the version, note in your dependency policy why (experimental, single maintainer, thin changelog), and diarise a re-evaluation — either the package reaches a stable 1.0 and you can relax the pin, or it goes quiet and you should plan the exit while the adapter boundary still makes that cheap.
How can I help you explore Laravel packages today?