Event Laravel Package

Getting Started

• Install with the 8.x constraint: composer require jbzoo/<package>:"^8.0". The 8.0 release is a coordinated ecosystem major, so pin every jbzoo/* package you use to ^8.0 in the same commit — mixed 7.x/8.x trees are the most likely source of pain.
• Confirm your runtime floor first. PHP 8.3+ is now mandatory (CI covers 8.3/8.4/8.5). Laravel 11/12 projects are already fine; Laravel 10 projects need 10.48+ and a PHP 8.3 runtime, plus an update to config.platform.php and your CI matrix (or composer.json require.php) so composer update resolves against the right target.
• Where to look first: composer.json (autoload map + require graph), the package README, then src/ for the primary entry classes (utilities, data/formatters, CLI helpers — the exact surface depends on which jbzoo/* package you pulled in). Since 8.0 is explicitly packaging-driven with no public API change, the 7.x docs remain a valid reference for behaviour.
• First use case: pick one leaf utility — a string/array helper, a typed data object, or a formatter — and consume it inside a small service or action class rather than in a controller or Blade template. That establishes the wrapping pattern you'll want for the rest of the package.

Implementation Patterns

• Wrap the API behind your own service. Most jbzoo/* packages lean on static helpers and value objects. Bind a thin adapter in a service provider ($this->app->singleton(MyFormatter::class)) and inject that into controllers, jobs, and commands. You get testability and a single place to touch on the next major.
• Keep it in the domain layer, not the framework layer. These are general-purpose PHP utilities; they belong in actions, value objects, casts, and Artisan commands. Avoid sprinkling static calls through Eloquent models and Blade — that couples your views to a third-party namespace.
• Use it for cross-cutting plumbing: input normalisation in Form Requests, custom Eloquent casts, console output formatting, and deterministic fixtures/assertions in tests. These are the areas where the utility-style API pays off fastest and is easiest to isolate.
• Upgrade workflow for this release: bump the constraint, run composer update "jbzoo/*" --with-all-dependencies, then composer why-not jbzoo/<package> 8.0 to catch anything still pinning a 7.x transitive. Because no public API changed, a green test suite is strong evidence the upgrade is complete — no code edits expected.
• Lockstep the ecosystem. If you use several JBZoo packages, upgrade them as one PR. Their inter-dependencies are all ^8.0, so a partial upgrade will either fail resolution or silently hold you on 7.x.

Gotchas and Tips

• The breaking change is the platform requirement, not the code. Treat 8.0 as an infrastructure upgrade: audit config.platform.php, CI images, Dockerfiles, and any php-version pins. A deployment image still on 8.2 will fail at install time, not at runtime — easy to miss locally.
• Don't mix majors. ^7.0 in one place and ^8.0 in another produces duplicate package installs or a hard resolution failure. After upgrading, run composer show | grep jbzoo and verify every entry is on 8.x.
• Static helpers resist mocking. If the package exposes static utility methods, you can't swap them in a unit test. Wrap them early (see above) or you'll end up writing integration tests for logic that should be pure.
• Treat vendor internals as private. Only the documented public classes are covered by the "no API change" promise; extending internal classes or reaching into protected members is where future majors will bite.
• Extension points to prefer: container bindings and your own adapter classes, plus any published config or custom formatter/renderer interfaces the package documents — those are the sanctioned seams. Subclassing concrete internals is not.
• Debugging resolution issues: composer why jbzoo/<package> and composer why-not jbzoo/<package> 8.0.0 tell you which package is blocking the bump; composer outdated --direct confirms what's actually installed versus available.
• Re-verify the README at 8.0. Even though the release is packaging-only, confirm the version tag on the docs you're following — older 7.x examples will still work, but the supported PHP range and dependency constraints have moved.