Ntlmsoapclient Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require capdigital/ntlmsoapclient
   

2. Enable Bundle (if using Symfony): Add to /config/bundles.php:

   Capdigital\NtlmSoapClient\CapdigitalNTLMSoapClient::class => ['all' => true]
   

3. Configure (/config/packages/capdigital_ntlm_soap_client.yaml):

   capdigital_ntlm_soap_client:
       url: "http://your-soap-server"
       port: "8080"
       server: "DOMAIN_SERVER"
       society: "COMPANY_NAME"
       user: "DOMAIN\\USERNAME"
       password: "PASSWORD"
   

4. First Use Case: Inject the service into a controller and call a SOAP method:

   use Capdigital\NtlmSoapClient\Service\CapdigitalNtlmSoapClient;
   
   class MyController extends Controller
   {
       public function index(CapdigitalNtlmSoapClient $ntlmClient)
       {
           $client = $ntlmClient->connect('SystemService');
           $result = $client->Companies();
           return response()->json($result->return_value);
       }
   }
   

Implementation Patterns

Dependency Injection

• Service Injection: Prefer constructor injection for testability:

  public function __construct(private CapdigitalNtlmSoapClient $ntlmClient) {}
  

• Lazy Loading: Defer connection until needed to avoid overhead:

  public function fetchData()
  {
      $client = $this->ntlmClient->connect('SystemService');
      // Use $client...
  }
  

Workflows

1. Reusable Connection Handling: Create a wrapper class for common SOAP calls:

   class CompanyService
   {
       public function __construct(private CapdigitalNtlmSoapClient $ntlmClient) {}
   
       public function getCompanies(): array
       {
           $client = $this->ntlmClient->connect('SystemService');
           return $client->Companies()->return_value;
       }
   }
   

2. Error Handling: Wrap SOAP calls in try-catch blocks:

   try {
       $result = $client->SomeMethod();
   } catch (SoapFault $e) {
       Log::error("SOAP Error: " . $e->getMessage());
       throw new \RuntimeException("SOAP service unavailable");
   }
   

3. Dynamic Configuration: Override config per environment (e.g., .env):

   # config/packages/capdigital_ntlm_soap_client.yaml
   capdigital_ntlm_soap_client:
       url: "%env(SOAP_URL)%"
   

Integration Tips

• Laravel Service Providers: Bind the service for easier testing:

  $this->app->bind(CapdigitalNtlmSoapClient::class, function ($app) {
      return new CapdigitalNtlmSoapClient(
          $app['config']['capdigital_ntlm_soap_client']
      );
  });
  

• Logging: Log SOAP requests/responses for debugging:

  $client->setDebug(true); // If supported (check package docs)
  

Gotchas and Tips

Pitfalls

1. NTLM Authentication:

   • Ensure the server supports NTLM. Test with tools like SoapUI first.
   • Domain/user format must match the server’s expectations (e.g., DOMAIN\user vs user@domain).

2. Connection Pooling:

   • The package may not handle connection reuse. Close connections explicitly if needed:

     $client = $ntlmClient->connect('ServiceName');
     // Use $client...
     $client->__soapCall('__soapClose'); // Hypothetical; verify API
     

3. Deprecated Methods:

   • The package is outdated (last release 2019). Assume undocumented behavior or missing features (e.g., WSDL caching, modern PHP versions).

4. Configuration Overrides:

   • Hardcoded values in the service may override YAML config. Inspect the connect() method for defaults.

Debugging

• Enable SOAP Debugging:

  $client = $ntlmClient->connect('ServiceName');
  $client->setUseCurl(true); // If supported
  ini_set('soap.wsdl_cache_enabled', 0); // Disable caching for testing
  

• Check Headers: Use a proxy (e.g., Charles) to verify NTLM headers are sent correctly.

Tips

1. Environment-Specific Config: Use Laravel’s config() helper to merge defaults:

   $config = array_merge([
       'url' => env('SOAP_URL'),
       'port' => env('SOAP_PORT', 80),
   ], config('capdigital_ntlm_soap_client'));
   

2. Testing: Mock the SOAP client for unit tests:

   $mockClient = $this->createMock(\SoapClient::class);
   $mockClient->method('Companies')->willReturn((object)['return_value' => []]);
   
   $this->app->instance(CapdigitalNtlmSoapClient::class, new class($mockClient) {
       public function connect($wsName) { return $this->client; }
   });
   

3. Fallback for Failures: Implement a retry mechanism for transient failures:

   use Symfony\Component\Process\Exception\ProcessFailedException;
   
   try {
       $result = $client->SomeMethod();
   } catch (SoapFault $e) {
       if (str_contains($e->getMessage(), 'timeout')) {
           sleep(2);
           return $this->fetchData(); // Recursive retry
       }
       throw $e;
   }
   

4. Security:

   • Avoid hardcoding credentials. Use Laravel’s env() or a secrets manager.
   • Restrict SOAP access to internal networks if possible.

5. Extending the Package:

   • Override the connect() method to add custom logic:

     class CustomNtlmSoapClient extends CapdigitalNtlmSoapClient
     {
         public function connect($wsName, $deleteSociety = false)
         {
             $client = parent::connect($wsName, $deleteSociety);
             $client->setUseCurl(true); // Example extension
             return $client;
         }
     }