Bkash Laravel Package

Getting Started

This release realigns the package with the current Laravel baseline and pulls in Apiz v4, so treat v2.0.0 as a new install target, not an in-place patch. Verify your constraints before anything else:

composer show <vendor>/<package> --all | grep -A3 requires

If you are on Laravel 7 or below, stay on the v1.x line — v2.0.0 requires laravel/framework ^8.0 and apiz ^4.0, and Composer will refuse to resolve otherwise.

Minimal setup path:

1. composer require <vendor>/<package>:^2.0
2. Confirm the service provider is registered (auto-discovery covers it on Laravel 8; add it manually only if you have dont-discover set).
3. Publish the config and diff it against any existing copy you had from v1:

   php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider" --tag=config
   

4. Inspect what the package registers before writing code — php artisan route:list and php artisan about will show whether routes and config are being loaded as expected.

Where to look first: the package's config/*.php and its src/Http (or equivalent) directory. The Apiz v4 bump almost certainly changed the response/transformer contract there, so read the formatter classes before reading the docs — the code is the source of truth for a major Apiz upgrade.

First use case: stand up a single read-only endpoint (one controller, one resource/transformer, one route) and assert the response envelope matches what you expect. That validates the whole chain — routing, middleware, serialization — in about ten minutes, and it surfaces most config drift immediately.

Implementation Patterns

Pin the major version, not the minor. With an Apiz major bump inside, ^2.0 is the correct constraint; ^2.0.1 invites accidental drift on a package that clearly makes breaking changes at major boundaries.

Isolate the response layer. Whatever Apiz v4 calls its transformer/formatter interface in your install, keep your own DTOs out of it. Map your domain objects to the package's contract in a thin adapter class, so a future Apiz v5 is a one-file change rather than a sweep through every controller.

Config-driven route registration. Most packages of this shape let you point a config key at a routes file or toggle route loading off entirely (common when you mount the endpoints under your own prefix or version group). Prefer your application's route files with the package's route-loading disabled if you need custom middleware — it is far easier to reason about than overriding arrays in config.

Middleware ordering matters. Versioning, auth, and any response-formatting middleware the package ships must run in a deliberate order inside your api group. Register the package middleware explicitly in app/Http/Kernel.php rather than relying on the package to append it, so the pipeline is visible in one place.

Test against the envelope, not the internals. Feature tests that assert HTTP status plus JSON structure (assertJsonStructure, assertJsonPath) survive internal refactors. Unit-testing the package's transformer in isolation ties your tests to a third-party contract that just proved it changes.

Upgrade workflow from v1.x:

composer require <vendor>/<package>:^2.0 -W
php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider" --tag=config --force
# diff the published config against version control before committing

Run --force with the config under version control so the diff shows exactly which keys were renamed, added, or dropped.

Gotchas and Tips

The Apiz v4 jump is the real breaking change, not the Laravel bump. Laravel 8 support is mostly a constraint-widening exercise; Apiz v4 is a major, which means any custom formatter, serializer, or response macro you wrote against v3 is a candidate for silent breakage. Grep your codebase for Apiz class imports before upgrading.

Silent failures in serialization. A formatter that no longer satisfies the v4 interface tends to fail at response time rather than boot time. If endpoints return empty bodies or {}, check the formatter binding first — that is the highest-probability culprit after a major upgrade.

Published configs go stale. Config published under v1 stays on disk through the upgrade and shadows the package's new defaults. Laravel merges package config with your published copy, so removed keys linger and renamed keys resolve to null. Republish and diff; do not assume the merge saves you.

Clear caches after upgrading, especially in environments using config:cache / route:cache. A cached route or config file from the previous version will produce errors that look like code bugs.

php artisan optimize:clear

Debugging checklist, in order: route:list (are routes registered?), php artisan config:show <package> (are the right values loaded?), container resolution of the transformer (app()->make(...) in tinker), then the actual response.

Extension points to find before you need them. Locate the package's binding for its response/formatter interface in the service provider and note it. Binding your own implementation in AppServiceProvider::register() is the cleanest way to customise output without forking — and it is also your escape hatch if a v4 behaviour regresses.

Watch transitive constraints. The Laravel 8 floor plus Apiz v4 can conflict with older laravel/sanctum, spatie/laravel-*, or PHPUnit majors. composer why-not is faster than reading the solver output.

No upgrade guide in these notes. The release note is one line, so budget time for a read of the package's UPGRADING.md or changelog — and if neither exists, treat the diff between v1 and v2 source as the migration document.