Apiwrapper Laravel Package

Getting Started

• Install with composer require negartarh/apiwrapper (v0.9.1 is the first release with Laravel 13 support; pin to ^0.9 until a 1.0 lands).
• Publish any package config/asset files with php artisan vendor:publish --provider="Negartarh\\ApiWrapper\\ApiWrapperServiceProvider" and review the generated config before writing code.
• Look first at the package's service provider (registered automatically via package discovery) and its config file — these tell you how HTTP clients, base URLs, and credentials are expected to be wired.
• First use case: wrap a single third-party API (one base URI + credentials), inject the wrapper into a controller or a small service class, and make one GET through it to confirm auth and error handling work end to end before expanding.

Implementation Patterns

• Dependency injection over facades where possible. Resolve the wrapper/client through the container so you can swap it with a fake in tests. If the package offers a facade, reserve it for quick scripts rather than core domain services.
• Configuration-driven clients. Keep base URLs, tokens, and timeouts in config/ (and .env), not in classes. This is what makes the wrapper reusable across environments and easy to cache with php artisan config:cache.
• Wrap, don't spread. Create thin domain-specific services (e.g., BillingClient, ShippingClient) that consume the package's client. This shields the rest of the app from pre-1.0 API churn.
• Service provider customization. v0.9.1's getPackageProviders change passes the Laravel Application instance, so you can conditionally register providers (e.g., only in non-production, or when a feature flag/credential is present).
• Test doubles. Use Laravel's HTTP client fakes or the package's own fake/contract (if provided) so integration tests don't hit live APIs; assert on the outgoing request shape rather than response bodies.
• Centralize error mapping. Catch transport/HTTP exceptions at the wrapper boundary and translate them into domain exceptions so controllers stay clean.

Gotchas and Tips

• Pre-1.0 instability. At v0.9.x, method signatures and config keys can shift without a major version bump. Pin the version, read the changelog on every upgrade, and keep usage behind your own service classes.
• Laravel version constraints. v0.9.1 added Laravel 13 support — verify the illuminate/* constraints in composer.json match your app before upgrading. If you're still on an older Laravel, check the v0.9.0 constraint set.
• getPackageProviders signature change. The new Application parameter is useful but can break custom subclasses or overrides that assumed the old signature. Update any overridden methods accordingly.
• Config caching. If config is cached in production, changes to published config files won't take effect until you re-run php artisan config:cache — a common cause of "it works locally" bugs.
• Debugging integrations. Enable Laravel's HTTP client logging (Http::withOptions(['debug' => ...]) or a logging middleware) around the wrapper to inspect real requests/responses; wrappers often obscure the underlying transport errors.
• Timeouts and retries. Don't rely on package defaults — set explicit connect/request timeouts and a retry policy for idempotent endpoints; a wrapper that silently retries non-idempotent calls can cause duplicate side effects.
• Extension points. Prefer extending via the published config and container bindings over forking the package; when a 1.0 release arrives, that separation makes the upgrade a matter of swapping the adapter rather than rewriting call sites.