Laravel Domain Whitelist Laravel Package

Getting Started

Version 1.2.0 is a compatibility release, not a feature release: it adds Laravel 10 and PHP 8.2 support. Treat it as "make it installable and keep it green on the newest stack" rather than "learn a new API."

1. Check your own floor first. Run php -v and php artisan --version. If you are on PHP 8.2 + Laravel 10, 1.2.0 is the first version that is explicitly supported — upgrade before anything else.
2. Install/upgrade within the same major: composer require vendor/package:^1.2. There is no major bump, so semver says 1.x → 1.2.0 is non-breaking. Verify with composer why-not vendor/package 1.2.0 if resolution fails.
3. Where to look first, in this order:
   • composer.json of the package (the require block tells you the real PHP/Laravel floor — "adds support" does not always mean "drops old support").
   • The service provider's register()/boot() — this is where config merges, bindings, and publish tags live.
   • config/*.php in the package — the knobs you will actually touch day-to-day.
   • The CHANGELOG/UPGRADE notes for anything that landed since the version you last ran.
4. First use case: on a scratch Laravel 10 app, php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (or --tag=package-config), set the required env vars, and exercise one documented example from the README in php artisan tinker. That single loop — publish, configure, call — is 90% of day-one usage.

Implementation Patterns

• Pin deliberately. Set "php": "^8.1|^8.2" and "laravel/framework": "^9.0|^10.0" in your app only after confirming the package's own constraints match. Don't hand-edit the lock file; let Composer resolve.
• Wrap it, don't sprinkle it. Resolve the package from the container (injected contract or facade) rather than instantiating classes directly. A thin app-level adapter/service around the package means the next compatibility bump touches one file, not forty.
• Prefer the package's own extension points over forking: config overrides, published views/migrations, bindings against its interfaces in a AppServiceProvider, and event listeners if it dispatches events.
• CI matrix. Add a job for PHP 8.2 / Laravel 10 alongside your existing 8.1/9 job. Most regressions from a support-bump release surface as deprecation noise on the newest runtime, which only shows up if you actually run it.
• Queue/deploy hygiene. If the package dispatches jobs or registers listeners, run php artisan queue:restart and php artisan optimize:clear in the deploy script — cached config and stale workers are the usual cause of "it works locally."
• Testing. Bind a fake/test double for the package's contract in a test service provider; keep integration tests that hit the real implementation behind a separate suite so unit tests stay fast.

Gotchas and Tips

• "Adds support" ≠ "requires." A 1.2.0 compatibility release will usually keep the old floor. Read composer.json before assuming you can (or must) drop Laravel 8/9 or PHP 8.0 from your matrix.
• PHP 8.2 deprecations are loud. Watch for "Creation of dynamic property … is deprecated" (fix on your side with #[AllowDynamicProperties] on your own models/DTOs, and report package-side occurrences upstream), plus deprecations around ${} string interpolation and utf8_encode/utf8_decode.
• Laravel 10 removals to sanity-check around the package: PHP 8.1 minimum, doctrine/dbal needed for some change() migrations, removal of $dates on models, and dropped deprecated helpers. If the package touches schema or dates, test those paths explicitly.
• Resolver conflicts are the #1 upgrade blocker: composer why-not laravel/framework ^10.0 finds the package holding you back. Transitive constraints from dev dependencies (phpunit, mockery) bite too.
• Config cache staleness. After upgrading, php artisan config:clear before debugging behavior that "didn't change" — merged package config is cached.
• A minor bump is still code. Run your test suite and a smoke test through the critical path; support-only releases occasionally carry incidental internal refactors.
• Debugging aids: php artisan about for environment drift, composer show -t for the dependency tree, and Telescope/log channels for anything the package does at runtime.