Laravel Luhn Laravel Package

Getting Started

• Install with composer require <vendor>/<package>, then confirm the service provider is auto-discovered (php artisan about or php artisan package:discover). Laravel 13 support landed in v1.0.14 — pin ^1.0.14 if the app is on Laravel 13, and don't rely on ^1.0 resolving to a compatible version from a stale lock file.
• Publish config and migrations before first use: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (add --tag=config / --tag=migrations to be selective). Review the published config file top-to-bottom once — it is the primary documentation for defaults.
• First use case: wire the package into a single, low-risk path (one controller or one queued job) rather than across the app. Run php artisan test plus one manual request against that path before broadening usage.
• Where to look first, in order: the published config file, the package's facade/entry class, its events and exceptions, then the changelog. If a README example doesn't match your installed version, trust the vendor directory source over the docs.

Implementation Patterns

• Bind through the container, not new. Resolve the package's main service from the container so config and any swapped implementations apply. If it ships a facade, use it for ergonomics but inject the underlying interface into constructors for testability.
• Wrap it behind your own interface. Define a thin App\Contracts\... adapter around the package's API. When the package changes shape (or you swap it), you change one class instead of every call site. This matters more for packages that expose static helpers.
• Config-driven, environment-scoped setup. Keep credentials and toggles in config/services.php or a dedicated config file, seeded from env vars, and add the keys to .env.example. Cache config (php artisan config:cache) as part of your deploy check — packages that read env() directly at runtime break under cached config.
• Queue long-running work. If the package performs HTTP calls or heavy IO (webhooks, syncs, exports), invoke it from a queued job with $tries, backoff(), and failed() handling rather than in the request cycle. Register the job's failure path before enabling it for real users.
• Prefer events over polling. If the package dispatches events (webhooks, state changes), listen to them and fan out to your own domain events. This keeps your app's behaviour independent of the package's internals and makes the integration replayable in tests.
• Testing setup. Use the package's fake/shouldReceive helpers (or bind a mock of your adapter) in feature tests. Add one integration test that hits the real code path against a sandbox/stub endpoint; keep it out of the default suite.
• Version discipline. Commit composer.lock, upgrade the package deliberately with composer update <vendor>/<package> --with-dependencies, and read the diff in vendor/ for anything touching config keys or method signatures before merging.

Gotchas and Tips

• Laravel 13 support does not mean older versions broke — verify anyway. Check the package's illuminate/* constraint in composer.json: a version that adds 13 support may simultaneously drop 11 or 12. If you're mid-upgrade across environments, pin per-branch.
• Stale lock files cause confusing resolution errors. If composer require fails with "conflicts with laravel/framework", it's usually the lock, not the constraint: composer update <vendor>/<package> rather than hand-editing composer.json.
• Config cache is the #1 debugging trap. After changing the package config, run php artisan config:clear (and queue:restart for workers). Symptoms of a stale cache look like the package ignoring your settings entirely.
• Published assets drift. Re-publish after upgrades with --force only after diffing, otherwise you'll silently overwrite local edits to config or migrations. Keep a note in your repo of which published files were modified.
• Auto-discovery can be disabled. If classes aren't found, check bootstrap/providers.php and any dont-discover entry in composer.json before assuming a package bug.
• Debug at the boundary. Log the inputs you hand the package and its raw response/exception message at the adapter layer. Package exceptions often wrap the real cause; report() alone will lose the upstream payload.
• Extension point of last resort. Prefer listening to the package's events or decorating its bound class in a service provider over subclassing internals or copying vendor code — the latter breaks silently on patch releases like this one.
• Watch the patch cadence. A 1.0.x line that ships a framework-compatibility bump is a good sign for maintenance; still, re-run your integration test after every bump, since patch releases can bundle untracked fixes.