Weave Code
Guzzle Services Laravel Package
guzzlehttp/guzzle-services
Guzzle Services adds a command layer on top of Guzzle using service descriptions to define operations, serialize requests, and parse responses into convenient model structures. Build typed clients from descriptions, call operations as methods, and get structured results.
Provides an implementation of the Guzzle Command library that uses Guzzle service descriptions to describe web services, serialize requests, and parse responses into easy to use model structures.
Frequently asked questions about Guzzle Services
- How do I integrate Guzzle Services with Laravel’s HTTP client for type-safe API calls?
- Replace Laravel’s `Http::get()` with a `GuzzleClient` bound to your service container. Define a service description (e.g., `StripeClient`) in `config/services.php`, then inject it into controllers/services. Example: `$client = new StripeClient($description); $charge = $client->createCharge(['amount' => 1000]);`. This enforces contracts and reduces manual parsing.
- Can I use Guzzle Services with Laravel 7 or older (pre-8.x) versions?
- No, Guzzle Services requires Guzzle 7+ (PHP 7.3+), which aligns with Laravel 8+. For older apps, use `guzzlehttp/guzzle-services:0.6` (Guzzle 5) or migrate to Laravel 8+. Check compatibility with `composer require guzzlehttp/guzzle-services:^1.0 --with-all-dependencies` and adjust your `php.ini` for PHP 8.x if needed.
- How do I handle API responses that return nested JSON objects or arrays?
- Define models in your service description to map responses to PHP objects. For example, include `'models': ['User' => ['type' => 'object', 'properties' => [...]]]` in your description. Guzzle Services will automatically parse nested structures into typed arrays/objects. Use `additionalProperties` for dynamic fields.
- Is there a way to reuse Guzzle middleware (e.g., retries, auth) with Laravel’s middleware stack?
- Yes. Bind Guzzle middleware to Laravel’s service container (e.g., `app.bind('stripe', fn() => new StripeClient($client, $description, $serializer))`). Extend Laravel middleware (e.g., `ThrottleRequests`) to wrap Guzzle middleware. Example: `$client->getEmitter()->getStack()->push(Middleware::authMiddleware(), 'auth');`
- How do I generate service descriptions for APIs without OpenAPI/Swagger specs?
- Manually define descriptions in PHP arrays or YAML files. Start with a simple example like the README, then expand for your API. Use tools like `gimler/guzzle-descr` to scaffold descriptions from existing API calls. For dynamic APIs, extend the `Description` class to load schemas at runtime.
- Will Guzzle Services work with Laravel’s queue system for async API calls?
- No, Guzzle Services is synchronous. For async workflows, dispatch Laravel jobs (e.g., `dispatch(new ProcessPayment($data))`) and use Guzzle inside the job. Alternatively, pair with `reactphp/react` for non-blocking HTTP calls, but this requires custom middleware integration.
- How do I test Guzzle Services clients in Laravel’s PHPUnit tests?
- Mock the `GuzzleClient` using Laravel’s `Mockery` or PHPUnit’s `createMock()`. Example: `$mock = Mockery::mock(GuzzleClient::class)->shouldReceive('createCharge')->andReturn($response)->getMock();`. Use `Http::fake()` for HTTP interactions, but replace it with your `GuzzleClient` for service-specific tests.
- Can I use Guzzle Services for GraphQL APIs or only REST?
- Guzzle Services is designed for REST APIs with predefined schemas. For GraphQL, use `webonyx/graphql-php` or `overblog/graphql-bundle`. Guzzle Services won’t handle GraphQL queries/mutations directly, but you can combine it with a GraphQL client for hybrid setups (e.g., REST for auth, GraphQL for data).
- How do I handle file uploads or multipart requests with Guzzle Services?
- Define a `multipart/form-data` operation in your description with `'location': 'form'` for file fields. Example: `'parameters': ['file' => ['type' => 'file', 'location' => 'form']]`. Pass files as `SplFileInfo` objects or arrays. Guzzle Services will serialize them correctly; ensure your API expects the same field names.
- What’s the best way to manage service descriptions across environments (dev/staging/prod)?
- Store descriptions in `config/api.php` with environment-specific overrides (e.g., `config/api/stripe.php`). Use Laravel’s `config()` helper to load them dynamically. For complex setups, externalize descriptions to JSON/YAML files and load them via `file_get_contents()` or `spatie/laravel-config-array`. Avoid hardcoding secrets in descriptions.
Weaver
How can I help you explore Laravel packages today?