Rest Bundle Laravel Package

Getting Started

This release adds array support to @ParamConverter for POST/PUT payloads — append [] to the class name in the annotation to receive a collection instead of a single object.

Minimal steps:

1. Install/update to v0.3.6 and clear any annotation/route caches:

   composer require <vendor>/<package>:^0.3.6
   php artisan cache:clear && php artisan route:clear
   

2. Look first at the existing converter registration (service provider / config) and any controller already using @ParamConverter — copy that pattern rather than inventing a new one.
3. First use case: a bulk endpoint. Send ids[]=1&ids[]=2 (or a JSON array) to a POST route and bind it to a collection:

   /**
    * @ParamConverter("users", class="App\Models\User[]")
    */
   public function bulkAssign(Request $request, array $users) { ... }
   

4. Sanity-check by dd($users) in the controller — confirm you get hydrated models, not raw arrays.

Implementation Patterns

The [] suffix is the switch. Same annotation, one character difference: class="App\Models\User" binds one record, class="App\Models\User[]" binds an indexed collection. Keep the single and bulk endpoints side by side in the codebase so the difference is obvious in review.

Bulk read / bulk mutation endpoints. This is the obvious fit: multi-select forms, admin tables with checkboxes, "apply to selected" actions. Instead of manual User::findMany($request->input('ids')), let the converter hydrate and 404 what's missing.

JSON payloads for API routes. Arrays travel naturally in application/json bodies; the converter should map a top-level array to the collection. Pair with a FormRequest for shape validation before the converter runs, so you fail fast on malformed input rather than on model lookup.

DTO collections. If you bind to a DTO class rather than an Eloquent model, the array form gives you a typed bag of request objects — useful for POST /orders with a line-items array.

Keep conversion and policy separate. The converter resolves objects; authorization still belongs in policies/gates per item. A converter that quietly drops unresolved IDs is a silent-failure risk in bulk operations — prefer "all or nothing" and assert the count matches the payload.

Integration tip: if you're on Laravel's route model binding most of the time, treat this package as the escape hatch for collections — don't mix both styles on the same resource, it confuses the next developer.

Gotchas and Tips

• [] is easy to lose in a refactor or a copy-paste. A missing suffix on a bulk endpoint won't error loudly; it'll bind the first record and silently discard the rest. Test the count explicitly.
• Payload shape matters. Form-encoded ids[]=1&ids[]=2 and JSON "ids": [1,2] are different paths — verify both, and verify what happens when only one ID is sent (should still return a one-element collection, not a single object).
• Empty arrays. [] in, [] out — make sure the converter returns an empty collection rather than throwing or 404ing, otherwise "nothing selected" becomes a 500.
• Nested arrays / arrays of arrays are almost certainly not supported by the [] suffix. Don't assume deep hydration; handle nested structures manually.
• Annotation caching. If you use a cached annotation reader (common in prod), the new [] parsing won't take effect until cache warm-up. Clear caches in deploy scripts.
• Debugging: log the raw input and the resolved collection count at the converter boundary. The most common bug report will be "only one item came through" — that's nearly always a missing suffix or a single-value payload.
• Extension point: if the built-in converter is too blunt for your validation needs, register a custom converter and keep the annotation surface unchanged. That also isolates you from future changes to the [] convention.
• Upgrade note: this is additive — existing non-array @ParamConverter usages are unaffected, so this is a low-risk bump.