Laravel Response Api Laravel Package

Getting Started

1. Install via Composer using the package’s Packagist name, then confirm Laravel auto-discovery registers ApiResponseServiceProvider. If your app disables package discovery, add the provider to bootstrap/providers.php or config/app.php.
2. Read the package README first, then inspect src/ApiResponse.php and src/ApiResponseBuilder.php. The 2.0.1 release specifically hardens these classes, so they are the best source of truth for available helpers.
3. Check whether the package publishes configuration:

   php artisan vendor:publish --provider="...\ApiResponseServiceProvider"
   

   Only publish if you need to change defaults; otherwise rely on package defaults to simplify upgrades.
4. Use the package’s tests as executable documentation. The 2.0.1 release added full coverage for created(), updated(), destroyed(), and pagination behavior, which makes those tests a reliable guide for expected response shapes and status codes.

First use case: standardize CRUD controller responses instead of hand-writing response()->json(...).

public function store(StoreUserRequest $request)
{
    $user = User::create($request->validated());

    return ApiResponse::created($user);
}

public function update(UpdateUserRequest $request, User $user)
{
    $user->update($request->validated());

    return ApiResponse::updated($user);
}

public function destroy(User $user)
{
    $user->delete();

    return ApiResponse::destroyed();
}

Verify the exact status code and body for destroyed() against your API contract before rolling it out broadly.

Implementation Patterns

• Use the builder as the single response boundary. Return ApiResponse::... from controllers and avoid mixing manual response()->json() calls with package responses. A consistent envelope is more valuable than any individual helper.
• Map CRUD helpers to HTTP semantics. Use created() after successful inserts, updated() after successful updates, and destroyed() after deletes. Keep the mapping in one place so status codes and JSON envelopes do not drift between controllers.
• Use pagination helpers for index endpoints. Return paginated results through the package rather than wrapping paginators manually. Confirm the resulting data, meta, and links keys match your frontend or API client expectations.
• Use ApiResponseBuilder for non-trivial responses. When you need a custom message, status, additional metadata, or headers, build the response fluently rather than constructing arrays by hand. This keeps custom responses aligned with the package’s default envelope.
• Normalize validation and exception responses. In bootstrap/app.php or your exception handler, render API exceptions through the same envelope. This prevents successful responses and error responses from using different JSON structures.
• Wrap the package behind your own responder when appropriate. For larger applications, create a small ApiResponder service that delegates to ApiResponse. This isolates future package upgrades and gives you one place to enforce project-specific conventions.
• Test the contract, not just the helper. Use Laravel’s assertStatus() and assertJsonStructure() around endpoints that use created(), updated(), destroyed(), and pagination. The package’s own 100% coverage is useful, but your application still needs to verify its expected API shape.
• Upgrade tooling separately from runtime dependencies. PHPStan ^2.0 and Rector ^2.0 are development tools. If your project extends or forks the package, align your static-analysis configuration with the package’s current setup; otherwise, no runtime action is required.

Gotchas and Tips

• This is a patch release, not a feature release. 2.0.1 contains bug fixes and tooling/test improvements. No new public API or deprecation is indicated, so upgrading from 2.0.0 should be low risk. If you are still on 1.x, review the 2.0 upgrade notes separately because this release does not describe those breaking changes.
• destroyed() response semantics matter. Confirm whether your version returns an empty 204 No Content response or a JSON body with 200 OK. Clients and tests often assume one or the other.
• Do not assume created() adds a Location header. If your API contract requires it, add it explicitly through the builder or response headers and cover it with a test.
• Pagination shape can break clients silently. The 2.0.1 PHPDoc fixes improve static analysis, but they do not change runtime behavior. If you have custom pagination wrappers, re-run PHPStan and verify the JSON structure after upgrading.
• Service provider registration in tests is a package-development concern, but it highlights a common consumer issue. If your test suite disables package discovery or uses Orchestra Testbench, ensure ApiResponseServiceProvider is registered explicitly.
• Clear cached config after publishing or changing package configuration. Use php artisan config:clear during development and redeploy with php artisan config:cache in production.
• Avoid extending package internals unless necessary. If you need custom behavior, prefer composing the builder or wrapping ApiResponse in your own service. Directly subclassing internal classes makes future upgrades harder.
• Debug the actual response object. When a response looks wrong, inspect the underlying JsonResponse with getStatusCode(), getContent(), and headers. This is faster than guessing whether the helper or your controller added the unexpected value.
• Keep API routes consistently JSON-oriented. If browser requests can hit the same endpoints, use middleware or request checks to ensure the package’s JSON envelope is only applied where clients expect it.
• Upgrade PHPStan and Rector cautiously in application repositories. The package moving to PHPStan ^2.0 and Rector ^2.0 does not force your app to upgrade, but if you share static-analysis configuration or copy the package’s setup, expect new rules and possibly new findings.