Service Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer (if available in a repository or forked manually):

   composer require guzzle/service
   

   (Note: Since this is a read-only subtree split of Guzzle 3, ensure compatibility with Laravel 4.x or legacy projects.)

2. Basic Usage The package provides a Service Client abstraction for interacting with RESTful APIs. Start with:

   use Guzzle\Service\Client;
   use Guzzle\Service\Description\ServiceDescription;
   
   // Load a service description (e.g., from a JSON file or API docs)
   $description = ServiceDescription::fromJson(file_get_contents('path/to/service.json'));
   
   // Initialize the client
   $client = new Client('https://api.example.com', [
       'description' => $description,
       'curl'        => [CURLOPT_SSL_VERIFYPEER => false] // Disable for testing
   ]);
   

3. First Use Case: Fetching Data Use the client to call an API endpoint:

   $response = $client->get('users', ['query' => ['limit' => 10]]);
   $users = $response->json();
   

Implementation Patterns

Workflows

1. Service Description Integration

   • Define API endpoints, parameters, and responses in a service.json file (e.g., generated from Swagger/OpenAPI).
   • Example structure:

     {
       "users": {
         "get": {
           "path": "/users",
           "httpMethod": "GET",
           "response": {
             "200": {
               "body": {
                 "type": "array",
                 "items": {"type": "object"}
               }
             }
           }
         }
       }
     }
     

   • Load it dynamically:

     $description = ServiceDescription::fromJson($json);
     $client = new Client('https://api.example.com', ['description' => $description]);
     

2. Request/Response Handling

   • Synchronous Calls:

     $client->get('users/{id}', ['path' => ['id' => 1]]);
     

   • Asynchronous Calls (if using Guzzle 3’s event system):

     $client->getAsync('users')->then(function ($response) {
         return $response->json();
     });
     

3. Middleware and Plugins

   • Attach middleware for logging, auth, or retries:

     $stack = new Guzzle\Service\Middleware();
     $stack->push(new Guzzle\Service\Middleware\AuthMiddleware('api_key', 'Bearer'));
     $client->setMiddlewareStack($stack);
     

4. Laravel Integration

   • Bind the client to the service container:

     $app->bind('api.client', function () {
         $description = ServiceDescription::fromJson(config('services.api.description'));
         return new Client(config('services.api.url'), [
             'description' => $description,
             'headers'     => ['Authorization' => 'Bearer ' . $app['auth']->token()]
         ]);
     });
     

   • Use dependency injection in controllers:

     public function index(Client $client) {
         $users = $client->get('users')->json();
         return view('users.index', compact('users'));
     }
     

Gotchas and Tips

Pitfalls

1. Guzzle 3 Compatibility

   • This package is a read-only subtree split of Guzzle 3, which is deprecated and lacks modern features (e.g., PSR-7, middleware stack improvements).
   • Avoid using it in new projects; prefer Guzzle 6/7 or Laravel HTTP Client.

2. Service Description Limitations

   • The ServiceDescription class is not auto-generated from modern API specs (e.g., OpenAPI 3). You must manually define the schema or convert from Swagger 1.2.
   • Example issue: Missing support for complex types (e.g., nested objects, arrays of objects).

3. No Built-in Retry Logic

   • Guzzle 3 lacks retry middleware. Implement manually:

     $stack->push(function ($request, $options) {
         if ($options['retry'] && $request->getError()) {
             return $request->getClient()->send($request, $options);
         }
     });
     

4. SSL Verification

   • Disabling SSL verification (CURLOPT_SSL_VERIFYPEER => false) is unsafe for production. Use proper certificates or a CA bundle:

     'curl' => [CURLOPT_CAINFO => __DIR__.'/path/to/cert.pem']
     

Debugging

• Enable Guzzle Debugging:

  $client->getEmitter()->attach(new Guzzle\Plugin\Log\LogPlugin(null, new \Monolog\Logger('name')));
  

• Inspect Raw Responses:

  $response = $client->get('users');
  \Log::debug($response->getBody(), ['headers' => $response->getHeaders()]);
  

Extension Points

1. Custom Response Parsers Override default JSON/XML parsing:

   $client->setResponseParser(function ($response) {
       return json_decode($response->getBody(), true);
   });
   

2. Dynamic Service Descriptions Fetch descriptions at runtime (e.g., from a config file or API):

   $description = ServiceDescription::fromJson(file_get_contents(config('api.description_url')));
   

3. Legacy Laravel 4 Support If using Laravel 4, bind the client to the IoC container:

   App::bind('api', function() {
       return new Client('https://api.example.com', ['description' => $this->getDescription()]);
   });