Filament Coord Picker Laravel Package

Getting Started

The v1.0.12 release is a compatibility release: it widens the framework constraint so the package can be installed on Laravel 12 applications. There are no new APIs to learn if you are already on the package — treat this as a green-light release rather than a feature release.

Minimum steps to get running on Laravel 12:

1. Confirm your app is on PHP 8.2+ and laravel/framework: ^12.0 — Laravel 12's own floor. The package cannot be the thing that pins you back.
2. composer require <vendor>/<package>:^1.0.12 (or composer update <vendor>/<package> if already installed). Pin at >=1.0.12; earlier 1.0.x tags will not resolve against Laravel 12 and Composer will either fail or silently downgrade your framework.
3. Check for a publishable config: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider". Most packages in this shape ship a config file that is the single most important thing to read.
4. Verify registration: php artisan about lists discovered providers; if the package is not there, its extra.laravel.providers entry is missing or you have a stale bootstrap/cache/packages.php (clear with php artisan package:discover).

Where to look first, in order: the service provider's register()/boot() methods, then the published config file, then the README's "quick start" example. The provider tells you what is bound into the container and under what key — that key is what you will type-hint everywhere else.

The first use case is almost always the same: resolve the package's primary service from the container in a controller or artisan command and call one method to prove the wiring works end to end before you build anything on it. Do that in php artisan tinker first, not in a real request.

Implementation Patterns

Inject, don't resolve. If the package exposes a manager or client class, type-hint it in the constructor. That gives you the container's configured singleton, and it gives tests a seam to swap. Reaching for app('package.key') or a facade inside business logic makes it much harder to substitute a fake later.

Keep configuration out of code. Copy the published config into your app's config/ and drive the package from there, including credentials via env(). Do not call the package's setters at runtime for values that belong in config — those are invisible to config:cache and to anyone reading the repo.

Wrap, then call. For anything beyond a trivial integration, put a thin application-level adapter around the package: one class with the handful of operations your domain actually needs (SendDigest, SyncRecord, etc.). When the package changes majors or you outgrow it, you change one file instead of grepping 40 call sites. This is the highest-leverage pattern for day-to-day use.

Fake it in tests. Bind a test double for the package's contract in setUp() or via a swap(), and assert on intent rather than on the package's internals. Then keep a small number of real integration tests (often tagged @group integration) that hit the actual service, so a version bump like this one is caught by something other than production.

Queue and events. If the package offers an async path (a job, a listener, a queued webhook), prefer it over inline calls in request cycles. Check the package's config/ for a queue name and connection key, and set those explicitly rather than inheriting your default queue — third-party work on your critical queue is a common cause of request latency spikes.

Version pinning with intent. Because this release is purely a framework-compat bump, pin ^1.0.12 and let patch releases flow, but constrain the major. If your composer.json uses * or a dev branch for this package, replace it now — that is how you ended up doing a surprise upgrade during a feature branch.

CI matrix. If you maintain the package or use it across several apps, run the test suite against Laravel 11 and 12 simultaneously after bumping. This release does not tell you whether 11 was dropped; check the composer constraint to confirm whether both are still supported before you assume you can upgrade incrementally across a fleet.

Gotchas and Tips

Stale caches after the upgrade. After composer update, run php artisan config:clear, php artisan cache:clear, and php artisan package:discover in that order. The single most common post-upgrade failure for config-driven packages is a cached config file referencing a key the new version renamed or removed. If behaviour looks impossible given the code, this is the first thing to check.

Constraint, not code. "Laravel 12 compat" in a release note almost always means only composer.json changed. Do not assume any bug you were hitting is fixed. Read the diff (composer show <vendor>/<package> --all, or the compare view between v1.0.11 and v1.0.12) — if it is a one-line constraint change, treat it as a no-op for behaviour and plan a real smoke test rather than relying on the version number.

Silent downgrades. On a mixed fleet, composer update on an older app can pull a lower 1.0.x. Lock files are per-project, so keep them in sync deliberately and review the composer.lock diff in code review — an unnoticed package downgrade is far more dangerous than the upgrade.

Config file drift. When a package adds a config key in a new version, your published copy does not gain it. Compare the package's shipped config against your published one after every bump; missing keys fall back to hardcoded defaults inside the package, which may not be the defaults you expect. Consider keeping your published config minimal and only overriding keys you actually change.

Deferred providers and boot order. If the package's provider is deferred, its bindings are not registered until first resolved — anything that relies on the binding existing at boot() time in your provider will fail. Force ordering with $this->app->register() in a dependency-explicit way, or move your logic to a later lifecycle point.

Migrations and publish tags. If the package ships migrations, vendor:publish overwrites nothing by default; use --force only when you have diffed the changes. Never run a package's migrations on production without reading them first, and never edit a published migration in place — the package's own copy will re-run against new environments.

Debugging checklist. In order: php artisan about (is it discovered?), composer show (what version actually installed?), config('package.key') in tinker (is config correct and not cached?), then the provider's register(). Ninety percent of "the package doesn't work" reports resolve at step one or two.

Extension points worth knowing. Before forking, look for: a contract you can rebind in your own provider, driver/managers registered via a extend()-style method, macros on the facade, and lifecycle events dispatched by the package. Most packages of this size expose at least a container rebind as an escape hatch, and a one-line rebind in AppServiceProvider is dramatically cheaper to maintain than a fork.

Record the upgrade. Note in your project changelog that the package is on v1.0.12 for Laravel 12 support. When the next major lands, knowing why you were on a particular patch version saves an archaeology session.