Download the PHP package siberfx/laravel-soap without Composer

Laravel SOAP

A modern, fluent SOAP client for Laravel. Register SOAP services once — in config or in code — and call them anywhere with Soap::call('Service.Method', $arguments). Includes class maps, SOAP headers, authentication, TLS/proxy options, events, readable exceptions and a testing fake so your test suite never touches a real SOAP endpoint.

Inspired by notfalsedev/laravel-soap, rewritten for PHP 8.4+ and Laravel 12/13.

Contents

• Requirements
• Installation
• Quick start
• Registering services
  • In code
  • In config
  • Global defaults
  • Non-WSDL mode
• Service options reference
• Calling operations
  • Class maps
  • SOAP headers
  • Working with the client directly
  • Debugging requests
• Error handling
• Events
• Testing
• Customisation
• Migrating from notfalsedev/laravel-soap
• Changelog
• License

Requirements

The PHP soap extension must be enabled.

Installation

The service provider and the Soap facade are registered automatically via package discovery.

Publish the configuration file (optional):

Quick start

Registering services

A service is a named SOAP endpoint. Each service gets its own lazily created, cached \SoapClient, built the first time you call it.

In code

Register services in a service provider's boot() method (for example AppServiceProvider):

add() also accepts the same array format used in the config file:

Registering the same name twice throws ServiceAlreadyExistsException. Use Soap::forget('Weather') first if you really need to replace a service. Other helpers:

You can also inject Siberfx\Soap\SoapWrapper instead of using the facade — it is bound as a singleton (also aliased as soap).

In config

Services in config/soap.php are registered automatically:

Supported keys: wsdl, location, uri, soap_version, trace, cache (or cache_wsdl), classmap, typemap, headers, stream_context, verify_ssl, client and options. Any other key is passed as-is to the native \SoapClient (e.g. login, password, authentication, proxy_host, local_cert, user_agent, keep_alive). null values are ignored, so unset environment variables fall back to the defaults.

Global defaults

soap.defaults is applied to every service — from config or code — before the service's own settings:

Tip: during development SOAP_WSDL_CACHE=0 avoids stale WSDLs after a remote change.

Non-WSDL mode

For services without a WSDL, provide location and uri instead:

A service with neither a WSDL nor both location and uri throws InvalidServiceConfigurationException when its client is built.

Service options reference

All methods return the service, so they can be chained.

exceptions is always true: failures are reported as exceptions, never as return values.

Read timeouts: PHP's SOAP extension reads responses using the default_socket_timeout ini setting. Use ini_set('default_socket_timeout', 60) for long-running operations.

The configured values are readable (but not writable) as properties, e.g. Soap::service('Weather')->wsdl, ->trace, ->classMap, ->headers, and ->toOptions() returns the exact options array passed to \SoapClient.

Calling operations

About $arguments: most WSDL services use the document/literal wrapped style, where an operation takes a single parameter object. Pass that object as the only element of the array:

Reading response headers requires a by-reference argument, which PHP cannot pass through a facade — call the injected SoapWrapper instead:

Class maps

Map WSDL complex types to your own classes to get typed requests and responses:

SOAP headers

Headers added on the service are sent with every call:

Headers for a single call:

Working with the client directly

Soap::client($name) returns the cached client — a Siberfx\Soap\SoapClient (an extended \SoapClient) unless you configured another class:

Pass a closure to receive the client and return a value:

Calls made directly on the client bypass the wrapper, so they are not faked, recorded, converted into SoapCallExceptions or reported through events. Prefer Soap::call().

Debugging requests

Enable trace() on a service (or SOAP_TRACE=true for all of them) and inspect the raw XML:

With trace enabled, the XML is also attached to SoapCallException and SoapResponseReceived.

Error handling

All package exceptions extend Siberfx\Soap\Exceptions\SoapException (a RuntimeException).

SoapCallException gives you everything about the failure:

Events

When soap.events is enabled (default), every Soap::call() dispatches:

Example: log slow or failing calls.

Arguments may contain credentials or personal data — scrub them before logging.

Testing

Call Soap::fake() and no request leaves your application. Every call is recorded so you can assert on it. Services do not even need to be registered while faked.

Stubs

Unmatched calls return null. To make them fail instead:

Soap::fake() can be called multiple times; stubs are merged.

Assertions

RecordedCall exposes service, method, arguments, target() ("Service.Method") and argument($key, $default) which supports dot notation into arrays and objects.

Customisation

Custom client class

Extend Siberfx\Soap\SoapClient (or \SoapClient) — for example to sign requests with WS-Security:

Custom client factory

All clients are built by Siberfx\Soap\ClientFactory. Bind your own subclass to change how every client is created:

Migrating from notfalsedev/laravel-soap

The API is intentionally familiar:

Development

The test suite runs real SOAP round-trips against an in-process SoapServer, so no network access is required. The soap extension must be enabled.

Changelog

See CHANGELOG.md.

License

The MIT License (MIT). See LICENSE.md.