Nbcsb Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package>. v3.0.0 requires Symfony >=7 <8, which pins the practical floor to Laravel 11+ and PHP 8.2+. On Laravel 10 or older, Composer will refuse to resolve; stay on the 2.x line.
• After install, run php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>" (or the tagged variants the README lists) and review what lands in config/. Most behaviour in this package is config-driven, so read that file end-to-end before writing code.
• Where to look first, in order: the README's quickstart block, the published config file, then the package's service provider (bindings + extension points). The provider is usually the fastest map of what you can swap out.
• First use case: wire the package into a single feature branch behind a config flag, verify it against a staging DB/queue, then roll out. Avoid enabling it globally on day one — the config surface is broad enough that defaults rarely match an existing app.

Implementation Patterns

• Constructor injection over facades. Resolve the package's main service through the container in constructors or via app(). This keeps it swappable in tests and lets you bind a fake/decorator in a test service provider.
• Config-first, env-second. Set sane defaults in config/<package>.php and only expose the values that genuinely differ per environment (credentials, endpoints, driver names) as env() calls. Commit the config; never commit .env.
• Feature-flagging during rollout. Wrap new call sites in a config boolean (config('package.enabled')) so a bad deploy is a config revert rather than a code revert.
• Test doubles. If the package makes outbound HTTP, queue jobs, or dispatches events, use Http::fake(), Queue::fake(), and Event::fake() around it rather than hitting real services. For DB-touching packages, RefreshDatabase plus a factory for the package's models covers most cases.
• Queue and event integration. Anything the package dispatches should be listened to rather than polled. Register listeners in a dedicated EventServiceProvider entry so package upgrades don't silently reorder your hooks.
• Multi-app / monorepo pinning. With a hard symfony/* constraint, pin the package to ^3.0 only in apps already on Symfony 7 components, and let older apps float at ^2.0. A composer why-not <vendor>/<package> 3.0 run tells you exactly which dependency is blocking.
• CI matrix. Add PHP 8.2/8.3 × Laravel 11/12 to the matrix. The Symfony 7 requirement means a green build on Laravel 10 tells you nothing about v3 compatibility.

Gotchas and Tips

• The Symfony bump is the real breaking change. >=7 <8 is not a cosmetic constraint update — it drops Laravel 10 and PHP 8.1 support and will fail resolution on those stacks. Treat v3.0.0 as a major upgrade requiring a Laravel major upgrade alongside it, not a drop-in patch.
• Debug resolution failures with composer why-not. If install fails, composer why-not <vendor>/<package> ^3.0 names the conflicting package. The usual culprits are older symfony/console, symfony/http-foundation, or a third-party package still capped at Symfony 6.
• The new .gitignore files are housekeeping, not behaviour. They typically sit in cache/storage/log directories so empty runtime dirs survive version control. Two consequences: vendor/ copies of the package may now contain .gitignore stubs your deploy script didn't expect, and rsync/git archive pipelines that exclude dotfiles will drop them. Check deploy scripts if you vendor or mirror the package.
• Don't expect the .gitignore additions to fix permission errors. If published storage/cache directories are unwritable, that's a filesystem/ownership issue; the package can't solve it.
• Clear caches after upgrading. php artisan config:clear && php artisan cache:clear && composer dump-autoload. Config caching is the number one cause of "the new version didn't change anything."
• Republish vs. merge configs. On a major bump, diff the package's shipped config against your published copy before overwriting — new keys appearing in v3 will silently fall back to package defaults if you keep a stale published file.
• Extension points to know: container bindings in the service provider, any Macroable traits on the package's classes, and custom driver/resolver registration. These are the sanctioned ways to adapt behaviour; avoid subclassing internals, which is where major-version churn bites.
• Watch the changelog for a v3.0.x follow-up. Release notes this thin (two lines for a major version) usually mean undocumented internal changes. Skim the diff between v2's last tag and v3.0.0 for signature changes before committing to the upgrade.