Settings Laravel Package

Getting Started

• Install with the matching constraint. composer require <vendor>/<package>:^5.1. This release adds PHP 8 support, so confirm your app's composer.json requires php: ^8.0 (or a range including it) before upgrading — Composer will otherwise resolve you back to a 5.0.x tag and you'll spend time debugging a version you aren't actually running.
• Verify what you're on first. Run composer show <vendor>/<package> and check the resolved version and its PHP constraint. If you were pinned to ^5.0, widen to ^5.1 explicitly rather than relying on a transitive bump.
• Read the service provider before the README. Look at src/*ServiceProvider.php for register() vs boot() behaviour: what gets bound as a singleton, what's published (config, migrations, views, assets), and whether anything is deferred. That answers most "why isn't my config change taking effect" questions up front.
• Publish only what you intend to own. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag=config (and --tag=migrations separately). Blanket vendor:publish without a tag can overwrite files you've already customised on the next upgrade.
• First use case: resolve the package's main entry point from the container in php artisan tinker before wiring it into a controller, call its simplest method against a throwaway record, and confirm the result. This isolates "package works" from "my integration works" — the two failures look identical from a stack trace.

Implementation Patterns

• Resolve, don't instantiate. Prefer constructor injection or app(Contract::class) over new PackageClass(...). The package's provider almost certainly binds a configured instance; new bypasses config, test doubles, and any decorators that get registered later.
• Facades for terse call sites, injection for testable ones. Facades are fine in controllers and Blade; in jobs, listeners, and services prefer the injected contract so you can swap in a fake without Facade::shouldReceive() ceremony.
• Wrap it behind your own adapter. A thin App\Services\... class that owns the package calls means the eventual v6 breaking change is one file to update, not a grep across forty. This is cheap insurance for anything used in more than one or two places.
• Queue-safe by default. If the package does I/O, mail, or HTTP, assume its objects aren't serialisable into a job payload. Pass scalars or your own DTOs into the job and resolve the package inside handle().
• Testing. Register fakes via the container/swap() in setUp() rather than hitting the network. If the package ships its own testing helpers or fake, use those first — they'll track upstream behaviour changes. For DB-touching packages, use RefreshDatabase and confirm published migrations run cleanly on SQLite in-memory if that's your CI default.
• Config-driven behaviour belongs in config/. Read tunables from config('<package>.php') in your own code rather than duplicating magic values, and set environment-specific overrides in .env where the package's config file supports env().

Gotchas and Tips

• PHP 8 support is a floor, not a rewrite. 5.1.0 claims PHP 8 compatibility; it doesn't mean your PHP 7.4 deployment can stay. Pin php in composer.json and let CI verify both your minimum and maximum supported minors. Run the upgrade on a branch with composer update <vendor>/<package> -W to see whether dependencies need nudging.
• PHP 8 behaviour shifts surface in dependencies too. Union types, str_contains-style native functions, and stricter type errors can change results for code that previously coerced silently — including code inside this package that was never designed for 8.x. Run your full suite, not just the package's tests.
• Config caching bites. After editing the published config on a cached deployment, php artisan config:clear (or config:cache in the deploy script) — otherwise your change appears to do nothing. Same story for route:cache if the package registers routes.
• Migrations in tests. Published migrations that assume MySQL (JSON columns, full-text indexes, enum) will fail on SQLite. Check before assuming a green local run means green CI.
• Silent no-ops are usually missing config keys. If calls succeed but nothing happens, dump config('<package>') — a null from an unset env() is the most common cause.
• Version pinning in libraries. If you're consuming this from a package rather than an app, require ^5.0 || ^5.1 (or ^5.1) and avoid dev-main, or downstream users hit constraint conflicts with your other dependencies.
• Extension points before forking. Check for published contracts, events, or a Macroable trait on the main class before editing vendor code. Most day-to-day customisation belongs in a decorated binding in your own provider.
• Keep an upgrade note. Record the resolved version and any published-file diffs (git diff after re-publishing to a scratch directory) so future upgrades show exactly which defaults changed — particularly useful now that the 5.0 → 5.1 jump changes the supported runtime.