Laravel Api Response Laravel Package

Getting Started

Install the package with Composer, then run the package’s install command if available (php artisan list will show the registered command). The release adds an installation command with a GitHub star prompt, so in CI or scripted environments use --no-interaction to avoid blocking on the prompt.

After installation:

1. Publish the package configuration and review the new exception-handler toggle. The service provider in 2.0.6 has improved config publishing, so republish if you rely on the packaged defaults.
2. Locate the published config file and decide whether the package’s custom exception handler should be enabled. If your application already has a global API exception formatter, leave it disabled to avoid competing handlers.
3. Open the LaravelApi facade and its underlying class. This is the primary day-to-day entry point for producing API responses.
4. Try the first use case: return a successful API response through the facade, then throw an exception from a controller and confirm the custom handler formats it consistently.

The documentation added in 2.0.6 for the facade, exception handling, and custom methods is the best first read. Start with the facade docs, then the exception-handler section, then the extension docs.

Implementation Patterns

Facade-first responses. Use the LaravelApi facade in controllers and actions rather than hand-building response arrays. This keeps success and error envelopes consistent. Wrap repeated response shapes in your own application-level helper or action class that delegates to the facade.

Custom methods via macros. The Macroable trait on LaravelApi is intended for project-specific response helpers. Register macros in a service provider’s boot method:

use LaravelApi;

LaravelApi::macro('paginated', function ($paginator) {
    return LaravelApi::success([
        'data' => $paginator->items(),
        'meta' => [
            'current_page' => $paginator->currentPage(),
            'total' => $paginator->total(),
        ],
    ]);
});

Keep macros small and domain-neutral. If a macro grows complex, move the logic into a dedicated response builder and have the macro delegate to it.

Exception handler integration. Enable the package exception handler when you want automatic API response formatting for uncaught exceptions. Keep domain exceptions expressive—throw meaningful exception types and let the handler map them to status codes and payloads. If you need per-exception formatting, use Laravel’s exception render methods or the package’s handler extension points rather than branching inside controllers.

Configuration-driven behavior. Treat the exception-handler toggle as environment-sensitive. It is reasonable to enable it in API-only environments and disable it where a legacy handler owns the response format. Clear config cache after changing it (php artisan config:clear).

Service provider customization. If you need to adjust bindings or register macros, do it in your own AppServiceProvider rather than editing vendor files. The improved publishing support means you can keep package config separate and override only the keys you need.

CI and coverage. The Codecov integration is for the package’s own repository, not a runtime feature. Do not add Codecov configuration to your application because of this release.

Gotchas and Tips

Named parameters can be a compatibility risk. The release changed internal function calls to use named parameters. In PHP 8+, parameter names are part of the public API. If your code calls package methods with named arguments and a parameter was renamed, the call will fail after upgrading. Prefer positional arguments for package calls unless the documentation explicitly stabilizes parameter names.

Do not run two exception formatters. Enabling the package’s custom exception handler while also customizing Laravel’s Handler or using another API response package can produce double-wrapped responses or inconsistent status codes. Test a 404, a validation error, and a deliberately thrown domain exception after enabling it.

Watch the install command in automation. The GitHub star prompt is friendly interactively but problematic in CI. Use --no-interaction and check whether the command performs any publishing steps you want to control separately.

Republish config carefully. “Improved configuration publishing” may mean new config keys. If you have an old published config file, diff it against the package’s current config. Missing keys can silently disable new behavior such as the exception-handler toggle.

Macros are global. Facade macros registered in one service provider are available everywhere. Use clear, prefixed names (apiPaginated, apiError) to avoid collisions with future package methods or other packages macroing the same class.

Debugging formatted exceptions. If the custom handler hides the original exception, check APP_DEBUG behavior and your logging configuration. During development, log the original exception before formatting, or temporarily disable the handler to confirm the underlying failure.

Configuration caching. After changing the exception-handler setting in production, run php artisan config:cache as part of deployment. A stale cached config is a common reason a toggle appears not to work.

Extension points. Prefer macros for response helpers and Laravel’s standard exception customization for error mapping. Avoid subclassing package internals unless the documentation explicitly supports it; the 2.0.6 changes show the package is still evolving, and internal method signatures are less stable than the facade and config surface.