Webservices Client Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require amf/webservices-client-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Amf\WebservicesClientBundle\AmfWebservicesClientBundle::class => ['all' => true],
   ];
   

2. Configuration: Define services in config/packages/amf_webservices_client.yaml:

   amf_webservices_client:
       services:
           my_soap_service:
               type: soap
               wsdl: 'http://example.com/soap?wsdl'
               options:
                   trace: true
           my_rest_service:
               type: rest
               base_uri: 'http://example.com/api'
               options:
                   headers:
                       Authorization: 'Bearer token123'
   

3. First Use Case: Inject the client in a service/controller and call a SOAP method:

   use Amf\WebservicesClientBundle\Service\WebservicesClient;
   
   class MyService
   {
       public function __construct(private WebservicesClient $client) {}
   
       public function fetchData()
       {
           $result = $this->client->call('my_soap_service', 'GetData', ['param1' => 'value1']);
           return $result;
       }
   }
   

Implementation Patterns

SOAP Workflows

1. Service Definition: Define SOAP services in YAML with WSDL and optional options (e.g., trace, exceptions).

   my_soap_service:
       type: soap
       wsdl: 'https://api.example.com/wsdl'
       options:
           trace: true
           exceptions: true
   

2. Method Invocation: Call SOAP methods dynamically:

   $response = $this->client->call('my_soap_service', 'MethodName', [
       'param1' => 'value1',
       'param2' => 123
   ]);
   

3. Response Handling: Process responses (XML/JSON) using Symfony’s Serializer:

   $data = $this->client->getSerializer()->decode($response, 'xml');
   

REST Workflows

1. Endpoint Configuration: Define REST endpoints with base URIs and headers:

   my_rest_service:
       type: rest
       base_uri: 'https://api.example.com/v1'
       options:
           headers:
               Accept: 'application/json'
               Authorization: 'Bearer token123'
   

2. HTTP Method Calls: Use named methods for clarity:

   // GET
   $response = $this->client->get('my_rest_service', '/users');
   
   // POST
   $response = $this->client->post('my_rest_service', '/users', [
       'name' => 'John Doe',
       'email' => 'john@example.com'
   ]);
   

3. Dynamic Paths/Queries: Use placeholders for dynamic routes:

   $response = $this->client->get('my_rest_service', '/users/{id}', [
       'id' => 42
   ]);
   

Integration Tips

• Dependency Injection: Bind the WebservicesClient to a custom interface for better testability:

  interface WebservicesClientInterface {
      public function call(string $serviceName, string $method, array $params);
  }
  

• Error Handling: Centralize error handling via middleware or a decorator:

  $this->client->call('my_soap_service', 'FaultyMethod', [])
      ->then(fn($result) => $result)
      ->otherwise(fn($error) => $this->handleError($error));
  

• Logging: Enable trace in SOAP options and log responses for debugging:

  options:
      trace: true
  

Gotchas and Tips

Pitfalls

1. SOAP WSDL Caching:

   • WSDL files may not update automatically. Clear cache after WSDL changes:

     php bin/console cache:clear
     

2. REST Authentication:

   • Hardcoded tokens in YAML are insecure. Use Symfony’s ParameterBag or environment variables:

     options:
         headers:
             Authorization: '%env(API_TOKEN)%'
     

3. XML/JSON Parsing:

   • SOAP responses are XML by default. Use Serializer to decode:

     $data = $this->client->getSerializer()->decode($response, 'xml');
     

4. Timeouts:

   • REST calls may hang. Set timeouts in options:

     options:
         timeout: 30
     

Debugging

1. SOAP Traces: Enable trace in options to log raw SOAP requests/responses:

   options:
       trace: true
   

   Check logs in var/log/dev.log.

2. REST HTTP Status Codes: Inspect raw responses for HTTP errors:

   $response = $this->client->get('my_rest_service', '/users');
   if ($response->getStatusCode() !== 200) {
       throw new \RuntimeException('API Error');
   }
   

3. Validation: Validate YAML configuration for typos in service names or WSDL paths.

Extension Points

1. Custom Serializers: Override the default Serializer by binding a custom service:

   services:
       my_serializer:
           class: MyApp\Serializer\CustomSerializer
           tags: ['serializer.encoder.xml']
   

2. Middleware: Add HTTP middleware (e.g., retry logic) by extending WebservicesClient:

   class CustomWebservicesClient extends WebservicesClient
   {
       protected function createClient(string $serviceName): ClientInterface
       {
           $client = parent::createClient($serviceName);
           $client->setHandlerStack(HandlerStack::create([
               new RetryMiddleware(),
           ]));
           return $client;
       }
   }
   

3. Dynamic Service Loading: Load services dynamically at runtime (e.g., from a database) by extending ServiceLoader.