Weave Code
Guzzle Services Laravel Package
guzzlehttp/guzzle-services
Build SDK-style API clients with service descriptions: map named operations and parameters to HTTP requests and transform responses into result data, instead of hand-writing request serializers for every endpoint.
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
- What is guzzlehttp/guzzle-services used for?
- It builds SDK-style HTTP clients from declarative service descriptions on top of guzzlehttp/command. You define named operations, parameters, URI templates, and response models as arrays, and the package maps them to HTTP requests and structured result data. It is framework-agnostic and intended for APIs with a wide integration surface, not for making a single HTTP call.
- Does guzzlehttp/guzzle-services work with Laravel?
- Yes, but it is framework-agnostic: there is no service provider, facade, or config publishing. In Laravel you typically bind a GuzzleClient as a singleton or factory and keep the description arrays in a config file or dedicated class. The main integration gate is the Guzzle major version, because Laravel's HTTP client uses Guzzle 7 while guzzle-services 2.0 requires Guzzle 8.
- How do I install guzzlehttp/guzzle-services in a Laravel app?
- Run composer require guzzlehttp/guzzle-services. For most Laravel applications today, plan on the ^1.7 line because it supports Guzzle ^7.15, while the 2.0 line requires Guzzle ^8. Then create a Description with baseUri, operations, and models, wrap a Guzzle Client in a GuzzleClient, and bind that instance in your container.
- What PHP and Laravel versions does guzzle-services support?
- The package itself has no Laravel version constraints. The 1.7 maintenance line supports PHP >=7.2.5,<8.7 and Guzzle ^7.15, while 2.0 supports PHP >=7.4,<8.7 and Guzzle ^8. Laravel compatibility is therefore determined by which Guzzle major your Laravel version uses, not by an explicit Laravel constraint in this package.
- guzzle-services vs Laravel Http facade: which should I use?
- Use Laravel's Http facade for one or a few endpoints, for example Http::withToken()->get(). Use guzzle-services when the integration surface is wide, roughly 20 or more named operations with uniform auth, pagination, error handling, and a desire to declare request serialization in arrays. Below about 10 operations, the Http facade plus a thin DTO layer is usually cheaper.
- Can guzzle-services import an OpenAPI or Swagger spec?
- No, there is no built-in OpenAPI or Swagger importer. Service descriptions are hand-authored arrays or produced by external codegen you own, which is the biggest functional gap versus alternatives like Saloon or generated SDKs. That also means vendor API drift shows up as runtime validation or parse errors rather than build failures, so consider a small in-house generator if a machine-readable spec exists.
- How do I define operations and parameters in a guzzle-services description?
- A Description array contains baseUri, an operations map, and a models map. Each operation specifies httpMethod, a uri template, a responseModel, and parameters with type and location such as uri, query, or json. You then call the client with named arguments, for example $client->getUser(['id' => '123']), and description authoring mistakes are generally caught at runtime.
- How do response models work in guzzlehttp/guzzle-services?
- The models key defines named response shapes, such as an object model with additionalProperties mapped to the json location. When an operation completes, the package maps response data into structured result data based on that model. Response models are permissive: unknown JSON can pass through additionalProperties, so they do not enforce a compile-time contract.
- How should I test a Laravel app that uses guzzle-services?
- Inject a Guzzle MockHandler or history middleware into the underlying Guzzle Client, then assert the requests produced by your service description and the mapped result data. Because the GuzzleClient is container-bound in Laravel, you can also swap it for a test double at your wrapper boundary. There are no Laravel-specific testing helpers in the package, so tests focus on operation definitions, serialization, and response mapping.
- Is guzzlehttp/guzzle-services actively maintained and secure?
- Yes, it is MIT-licensed, actively released, and backed by a published security policy with Tidelift-mediated disclosure. It has shipped fixes for issues such as XML CDATA injection, and 2.0 adds API-key redaction in PHP 8.2+ backtraces. Note that 1.7 already carries forward-looking deprecations for the 2.0 migration, so it is best treated as a transitional line while Laravel remains on Guzzle 7.
Weaver
How can I help you explore Laravel packages today?