Soap

A Laravel SOAP client that provides a clean interface for handling requests and responses.

Docs

• Soap
  • Docs
  • Requirements
  • Installation
  • Using Soap
  • Features/API
    • Headers
      • Global Headers
    • To
    • Functions
    • Call
      • Parameters
        • Nodes
    • Options
      • Tracing
      • Authentication
      • Global Options
  • Hooks
    • Local
    • Global
  • Faking
    • Inspecting requests
      • Soap::assertSentCount($count)
      • Soap::assertSent(callable $callback)
      • Soap::assertNotSent(callable $callback)
      • Soap::assertNothingSent()
  • Configuration
    • Include
  • Ray Support
    • ray()->showSoapRequests()
    • ray()->stopShowingSoapRequests()
    • Changelog
  • Contributing
    • Security
  • Credits
  • License

Requirements

• PHP 8.2 or greater
• Laravel 12 or greater

Installation

You can install the package via composer

composer require ricorocks-digital-agency/soap

Using Soap

Soap can be accessed through the provided Facade

use RicorocksDigitalAgency\Soap\Facades\Soap

Soap::to()

Features/API

Headers

You can set the headers for each soap request that will be passed to the Soap Client using the withHeaders method.

Soap::to('...')->withHeaders(...$headers)->call('...');

Each header should be a Header instance, which provides a fluent interface for constructing a new PHP Soap Header and can be composed as follows:

$header = Soap::header()
            ->name('Authentication')
            ->namespace('test.com')
            ->data([
                'user' => '...',
                'password' => '...'
            ])
            ->mustUnderstand()
            ->actor('foo.co.uk')

This can also be expressed as:

$header = Soap::header('Authentication', 'test.com', [
                'user' => '...',
                'password' => '...'
            ])
            ->mustUnderstand()
            ->actor('foo.co.uk')

Plus, the soap_header helper method can be used:

$header = soap_header('Authentication', 'test.com')
            ->data([
                'user' => '...',
                'password' => '...'
            ])

The data for the header can either be an array or a SoapVar, as per the SoapHeader constructor

Global Headers

Soap allows you to set headers that should be included for every request:

Soap::headers(...$headers)

Again, each header should be an instance of Header.

You may also want to include headers on every request, but only for a certain endpoint or action:

// Only requests to this endpoint will include these headers
Soap::headers(soap_header('Auth', 'test.com'))->for('https://api.example.com');

// Only requests to this endpoint and the method Customers will include these headers
Soap::headers(soap_header('Brand', 'test.com'))->for('https://api.example.com', 'Customers');

These calls are usually placed in the boot method of one of your application's Service Providers.

To

The endpoint to be accessed

Soap::to('github.com/api')

Functions

Retrieve the functions the endpoint provides

Soap::to('github.com/api')->functions()

This is a wrapper for the PHP SoapClient _getFunctions() method.

Call

Call the method at the endpoint.

Soap::to('github.com/api')->call('merge')

The method can also be called as a Magic Method.

Soap::to('github.com/api')->merge()

Parameters

The Call method of course accepts parameters. The parameters passed can be an array

Soap::to('github.com/api')->call('merge', ['branch' => 'staging', 'credentials' => ['password' => '...'])

Nodes

To simplify dealing with SOAP XML in your requests, Soap provides a method to fluently construct the nodes in the request.

For example, say the following node was desired in the XML request. Note it has no body.

<PullRequest branch="dev" target="main">
</PullRequest>

The array to pass to the underlying php SoapClient to construct this node would be as follows

'PullRequest' => [
    '_' => '',
    'branch' => 'dev',
    'target' => 'main'
]

The _ is required to set the information not as the body, but as the attributes for the node.

However, this is not required if the XML node has a body.

<PullRequest branch="dev" target="main">
    <Author>Ricorocks</Author>
</PullRequest>

Now, the array would be as follows

'PullRequest' => [
    'Author' => 'Ricorocks',
    'branch' => 'dev',
    'target' => 'main'
]

So, to prevent confusion, the Soap::node() will allow for intelligent construction of the php array to be passed to SoapClient.

Imagine we are accessing the information method to see details about Pull Requests

Soap::to('...')
    ->information('PullRequest' => soap_node(['branch' => 'dev', 'target' => 'main']))

'PullRequest' => [
    '_' => '',
    'branch' => 'dev',
    'target' => 'main'
]

Soap::to('...')
    ->information('PullRequest' => soap_node(['branch' => 'dev', 'target' => 'main'])->body(['Author' => 'Ricorocks']))

'PullRequest' => [
    'Author' => 'Ricorocks',
    'branch' => 'dev',
    'target' => 'main'
]

Now, just by adding or removing a body to the soap_node() the outputted array is intelligently constructed.

A node can be made with either the Facade Soap::node() or the helper method soap_node().

Options

You can set custom options for each soap request that will be passed to the Soap Client using the withOptions method.

Soap::to('...')->withOptions(['soap_version' => SOAP_1_2])->call('...');

See https://www.php.net/manual/en/soapclient.construct.php for more details and available options.

Soap also provides a number of methods that add syntactical sugar to the most commonly used options, which are detailed below.

Tracing

Soap allows you to easily trace your interactions with the SOAP endpoint being accessed.

To trace all requests, set the following in the register method of your ServiceProvider:

Soap::trace()

Now, all Response objects returned will have a Trace object attached, accessible via $response->getTrace(). This has four properties which are wrappers for the respective methods found on the SoapClient:

• xmlRequest (__getLastRequest)
• xmlResponse (__getLastResponse)
• requestHeaders (__getLastRequestHeaders)
• responseHeaders (__getLastResponseHeaders)

Tracing can also be declared locally:

Soap::to('...')->trace()->call('...')

Now, just this Response will have a valid Trace.

Tracing is null safe. If $response->getTrace() is called when a Trace hasn't been set, a new Trace is returned. This Trace's properties will all return null.

Authentication

You can authenticate using Basic or Digest by calling withBasicAuth and withDigestAuth respectively.

Soap::to('...')->withBasicAuth('username', 'password')->call('...');
Soap::to('...')->withDigestAuth('username', 'password')->call('...');

Global Options

Sometimes, you may wish to include the same set of options on every SOAP request. You can do that using the options method on the Soap facade:

// Every request will include these options automatically
Soap::options(['login' => 'foo', 'password' => 'bar']);

You may also want to include options on every request, but only for a certain endpoint or action:

// Only requests to this endpoint will include these options
Soap::options(['login' => 'foo', 'password' => 'bar'])->for('https://api.example.com');

// Only requests to this endpoint and the method Customers will include these options
Soap::options(['login' => 'foo', 'password' => 'bar'])->for('https://api.example.com', 'Customers');

These calls are usually placed in the boot method of one of your application's Service Providers.

Hooks

Hooks allow you to perform actions before and after Soap makes a request. These hooks can be local (per request), or global (applied to every request).

You can make changes to the Request object in beforeRequesting hooks if you wish. These changes will be reflected in the actual request. In fact, this is how the Soap include functionality works.

Local

To create a local hook, chain beforeRequesting, afterErroring or afterRequesting to a Request object:

Soap::to('http://example.com')
	->beforeRequesting(fn() => Log::info('Request going in!'))
	->afterRequesting(fn() => Log::info('Request coming out!'))
	->afterErroring(fn() => Log::error('An error occurred!'))
	->call('Action', []);

Any before requesting hooks will receive the request as a parameter. After Erroring hooks will receive the request and exception as parameters. After requesting hooks will receive the request and response as parameters.

Global

To create a global hook, use the Soap::beforeRequesting, Soap::afterErroring, and Soap::afterRequesting methods.

Soap::beforeRequesting(fn() => Log::info('Request going in!'));
Soap::afterErroring(fn() => Log::error('An error occurred!'));
Soap::af