PHP: полный мануал с примерами, функциями и ООП

<?php
declare(strict_types=1);

$ok = (object) ['status' => 'paid'];
$fault = new SoapFault('Server', 'Склад временно недоступен');

echo is_soap_fault($ok) ? "fault\n" : "result\n";
echo is_soap_fault($fault) ? "fault\n" : "result\n";

result
fault

Проверка не анализирует строку и не считает любой Exception SOAP-ошибкой: она отвечает, является ли значение именно SoapFault. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';

$client = new ManualMockSoapClient(
    manualSoapFault('Server', 'Товар не найден'),
    null,
    ['exceptions' => false],
);
$result = $client->__soapCall('findProduct', [['sku' => 'NO-404']]);

if (is_soap_fault($result)) {
    echo "fault: {$result->faultstring}\n";
} else {
    echo "product received\n";
}

fault: Товар не найден

При exceptions=false не сработает catch: Fault приходит как возвращаемый объект, поэтому проверка должна стоять сразу после вызова. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$initial = use_soap_error_handler(false);
$previous = use_soap_error_handler(true);
echo $previous === false ? "до включения: обычный handler\n" : "unexpected\n";
use_soap_error_handler($initial);
echo "настройка восстановлена\n";

до включения: обычный handler
настройка восстановлена

Функция возвращает прошлое значение, поэтому библиотека может аккуратно восстановить окружение после локального опыта или теста. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';

function loadWarehouse(): string
{
    missing_inventory_driver(); // намеренная ошибка учебного обработчика
    return 'never';
}

use_soap_error_handler(true);
$server = new SoapServer(null, ['uri' => 'urn:manual', 'send_errors' => false]);
$server->addFunction('loadWarehouse');
$xml = manualHandle($server, manualSoapRequest('loadWarehouse', []));
echo manualXmlValue($xml, 'faultstring'), "\n";

Internal Error

SOAP handler превращает фатальную ошибку в корректный Envelope. send_errors=false не выдаёт клиенту имя внутренней функции; подробности пишут в закрытый журнал процесса. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$fault = new SoapFault(
    ['urn:shop', 'OrderRejected'],
    'Order cannot be confirmed',
    'urn:shop:checkout',
    ['orderId' => 731, 'reason' => 'stock'],
    'OrderFault',
    null,
    'ru',
);
echo $fault->faultcode, "\n";
echo $fault->faultstring, "\n";
echo $fault->detail['orderId'], ' / ', $fault->lang, "\n";

OrderRejected
Order cannot be confirmed
731 / en

QName-код, понятное сообщение и structured detail отделяют машинный договор от текста. В PHP 8.5.11 аргумент lang у прямого SoapFault::__construct разбирается, но exact source всё ещё записывает en; для реально сериализованного SOAP 1.2 Reason используйте проверенный SoapServer::fault и contract test. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

try {
    throw new SoapFault('Client', 'Неверный код склада');
} catch (SoapFault $fault) {
    echo "SOAP {$fault->faultcode}: {$fault->faultstring}\n";
    echo "HTTP ответ приложения: 422\n";
}
try {
    new SoapFault(['urn:shop'], 'Неполный QName');
} catch (ValueError $error) {
    echo "invalid QName rejected\n";
}

SOAP Client: Неверный код склада
HTTP ответ приложения: 422
invalid QName rejected

SoapFault наследует Exception, поэтому участвует в обычном try/catch. QName-массив обязан состоять ровно из namespace URI и local code; неполный массив даёт ValueError. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$fault = new SoapFault('Server', 'Сервис доставки не ответил');
$text = (string) $fault;
echo str_contains($text, 'SoapFault') ? "class present\n" : "class missing\n";
echo str_contains($text, 'Сервис доставки не ответил') ? "message present\n" : "message missing\n";

class present
message present

Полная строка похожа на строку Exception и содержит файл/trace, поэтому тест проверяет смысловые признаки, а не нестабильные номера строк. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$fault = new SoapFault('Server', 'Timeout', 'urn:carrier', ['requestId' => 'req-42']);
$raw = $fault->__toString();
$requestId = is_array($fault->detail) ? ($fault->detail['requestId'] ?? '-') : '-';
printf("soap_fault code=%s actor=%s request=%s\n", $fault->faultcode, $fault->faultactor, $requestId);
echo str_contains($raw, 'SoapFault') && str_contains($raw, 'Timeout') ? "raw trace captured\n" : "raw trace missing\n";

soap_fault code=Server actor=urn:carrier request=req-42
raw trace captured

Пример действительно вызывает __toString(), но в стабильную строку журнала выводит отдельные поля. Полную трассировку сохраняют отдельно с контролем доступа. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$header = new SoapHeader(
    'urn:shop:auth',
    'Credentials',
    ['login' => 'robot-17', 'token' => 'demo-token'],
    true,
    SOAP_ACTOR_NEXT,
);
echo $header->namespace, "\n";
echo $header->name, ' / ', ($header->mustUnderstand ? 'required' : 'optional'), "\n";
try {
    new SoapHeader('urn:shop:auth', 'Credentials', null, false, 999);
} catch (ValueError $error) {
    echo "invalid actor rejected\n";
}

urn:shop:auth
Credentials / required
invalid actor rejected

Namespace — URI словаря сервиса, name — имя элемента, data — его содержимое. Integer actor разрешён только как SOAP_ACTOR_NEXT, SOAP_ACTOR_NONE или SOAP_ACTOR_UNLIMATERECEIVER. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';

$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '7'));
$client->__setSoapHeaders(new SoapHeader(
    'urn:shop:auth',
    'Credentials',
    ['login' => 'robot-17', 'token' => 'demo-token'],
));
$client->__soapCall('sum', [new SoapParam(3, 'a'), new SoapParam(4, 'b')]);

echo str_contains($client->seenRequest, '<SOAP-ENV:Header>') ? "header present\n" : "header missing\n";
echo str_contains($client->seenRequest, 'demo-token') ? "token present\n" : "token missing\n";

header present
token present

Trace/XML подтверждает фактическую сериализацию. В реальном журнале токен маскируют; здесь используется учебное значение. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$parameter = new SoapParam(731, 'orderId');
echo $parameter->param_name, "\n";
echo $parameter->param_data, "\n";
try {
    new SoapParam(731, '');
} catch (ValueError $error) {
    echo "empty name rejected\n";
}

orderId
731
empty name rejected

Объект связывает PHP-значение 731 с именем orderId. Пустое имя отклоняет сам PHP с ValueError до сериализации. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';

$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '7'));
$result = $client->__soapCall('sum', [
    new SoapParam(3, 'a'),
    new SoapParam(4, 'b'),
]);
echo $result, "\n";
echo preg_match('/<a[^>]*>3<\/a>/', $client->seenRequest) ? "a named\n" : "a missing\n";
echo preg_match('/<b[^>]*>4<\/b>/', $client->seenRequest) ? "b named\n" : "b missing\n";

7
a named
b named

Это полезно в non-WSDL режиме, где клиент не может взять имена из контракта. В WSDL-mode обычно достаточно обычного массива, если WSDL корректен. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$date = new DateTimeImmutable('2026-10-15T12:30:00+03:00');
$value = new SoapVar($date, XSD_DATETIME, null, null, 'shippedAt', 'urn:shop');
echo $value->enc_type === XSD_DATETIME ? "xsd:dateTime\n" : "other\n";
echo $value->enc_name, ' / ', $value->enc_namens, "\n";
try {
    new SoapVar('value', 999999);
} catch (ValueError $error) {
    echo "unknown encoding rejected\n";
}

xsd:dateTime
shippedAt / urn:shop
unknown encoding rejected

С PHP 8.4 DateTimeInterface для xsd:dateTime сериализуется как ISO 8601. Неизвестный numeric encoding PHP отклоняет ValueError до сериализации. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';

$client = new ManualMockSoapClient(manualSoapResponse('upload', 'string', 'accepted'));
$payload = new SoapVar("PDF\x00demo", XSD_BASE64BINARY, null, null, 'content', 'urn:files');
$result = $client->__soapCall('upload', [new SoapParam($payload, 'file')]);
echo $result, "\n";
echo str_contains($client->seenRequest, base64_encode("PDF\x00demo")) ? "base64 payload\n" : "payload missing\n";

accepted
base64 payload

SoapVar сообщает сериализатору XSD-тип; бинарные байты не вставляются в XML напрямую, а кодируются Base64. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';

$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '9'));
$result = $client->__soapCall('sum', [new SoapParam(4, 'a'), new SoapParam(5, 'b')]);
echo $result, "\n";
echo $client->seenLocation, "\n";

9
http://local.invalid/soap

В non-WSDL mode приложение само задаёт location и uri. Mock заменяет только сеть; Envelope создаёт и разбирает настоящий ext/soap. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';

$client = new ManualMockSoapClient(
    manualSoapResponse('sum', 'int', '15'),
    __DIR__ . '/service.wsdl',
    ['cache_wsdl' => WSDL_CACHE_NONE],
);
echo $client->__getFunctions()[0], "\n";
echo $client->sum(7, 8), "\n";

int sum(int $a, int $b)
15

WSDL задаёт имя, типы, SOAPAction и endpoint. Cache отключён только в локальном изменяемом контракте; production WSDL обычно версионируют и кэшируют. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';

$client = new ManualMockSoapClient(
    manualSoapResponse('sum', 'int', '12'),
    __DIR__ . '/service.wsdl',
);
echo $client->sum(5, 7), "\n";
echo str_contains($client->seenAction, 'sum') ? "action: sum\n" : "action: other\n";

12
action: sum

Когда PHP не находит реальный метод sum, magic dispatch направляет вызов в SoapClient::__call. Такой синтаксис — обычный путь для WSDL-клиента. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';

$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '7'));
$old = $client->__call('sum', [new SoapParam(3, 'a'), new SoapParam(4, 'b')]);
$new = $client->__soapCall('sum', [new SoapParam(3, 'a'), new SoapParam(4, 'b')]);
echo 'direct: ', $old, "\n";
echo 'soapCall: ', $new, "\n";

direct: 7
soapCall: 7

Прямой вызов __call() документация помечает deprecated, хотя проверенный runtime 8.5.11 не обязан выдавать E_DEPRECATED. Результат показан рядом с явным __soapCall(); magic $client->sum() остаётся нормальным WSDL-синтаксисом. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';

$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '7'));
$result = $client->__soapCall(
    'sum',
    [new SoapParam(3, 'a'), new SoapParam(4, 'b')],
    ['location' => 'https://backup.example.test/soap', 'soapaction' => 'urn:manual#sum'],
);
echo $result, "\n";
echo $client->seenLocation, "\n";

7
https://backup.example.test/soap

Per-call location не меняет WSDL и удобен для управляемого failover. Endpoint всё равно берут из доверенной конфигурации, а не из пользовательского ввода. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';

$replyHeader = '<m:RequestId xmlns:m="urn:meta">req-42</m:RequestId>';
$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '7', $replyHeader));
$responseHeaders = [];
$result = $client->__soapCall(
    'sum',
    [new SoapParam(3, 'a'), new SoapParam(4, 'b')],
    null,
    new SoapHeader('urn:meta', 'ClientId', 'shop-1'),
    $responseHeaders,
);
echo $result, "\n";
echo $responseHeaders['RequestId'], "\n";

7
req-42

Пятый аргумент — выходной: PHP заполняет переданную переменную. Это SOAP headers внутри Envelope, не HTTP response headers. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';

$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '7'));
echo $client->__soapCall('sum', [new SoapParam(3, 'a'), new SoapParam(4, 'b')]), "\n";
printf("version=%d action=%s\n", $client->seenVersion, $client->seenAction);
echo str_contains($client->seenRequest, '<a xsi:type="xsd:int">3</a>') ? "body checked\n" : "body differs\n";

7
version=1 action=urn:manual#sum
body checked

Переопределение получает уже готовый Envelope и transport metadata. Это точка для test double, очереди или нестандартного транспорта, но не повод переписывать XML строковыми заменами. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$url = getenv('SOAP_TEST_URL') ?: throw new RuntimeException('SOAP_TEST_URL missing');
$request = '<?xml version="1.0"?>'
    . '<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">'
    . '<SOAP-ENV:Body><m:sum xmlns:m="urn:manual"><a>1</a><b>2</b></m:sum></SOAP-ENV:Body>'
    . '</SOAP-ENV:Envelope>';
$client = new SoapClient(null, ['location' => $url, 'uri' => 'urn:manual', 'exceptions' => false]);
$success = $client->__doRequest($request, $url, 'urn:manual#sum', SOAP_1_1, true);
echo $success === '' ? "success: empty string\n" : "success: unexpected\n";
$failure = $client->__doRequest($request, 'http://127.0.0.1:1/unavailable', 'urn:manual#sum', SOAP_1_1, true);
echo $failure === null ? "failure: null\n" : "failure: unexpected\n";

success: empty string
failure: null

Base transport PHP 8.5.11 при oneWay=true возвращает пустую строку после успешной отправки и null при transport failure. Это не подтверждение обработки бизнес-события. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; HTTP endpoint — одноразовый loopback-сервер, без внешней сети.

<?php
declare(strict_types=1);

$client = new SoapClient(null, ['location' => 'http://local.invalid', 'uri' => 'urn:manual']);
$client->__setCookie('manual_session', 'abc');
$client->__setCookie('region', 'msk');
$client->__setCookie('region');
$cookies = $client->__getCookies();
echo $cookies['manual_session'][0], "\n";
echo array_key_exists('region', $cookies) ? "region kept\n" : "region removed\n";

abc
region removed

Cookie jar хранит дополнительные атрибуты массивом. Не предполагайте, что значение всегда лежит прямо по ключу без вложенности. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$url = getenv('SOAP_TEST_URL') ?: throw new RuntimeException('SOAP_TEST_URL missing');
$client = new SoapClient(null, ['location' => $url, 'uri' => 'urn:manual']);
$client->__setCookie('manual_session', 'cart-731');
echo $client->__soapCall('readManualCookie', []), "\n";
echo $client->__getCookies()['manual_session'][0], "\n";

cart-731
cart-731

Здесь cookie прошёл через настоящий HTTP loopback. Для удалённого сервиса помните про область домена/path/secure и не выводите session token. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; HTTP endpoint — одноразовый loopback-сервер, без внешней сети.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';
$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '0'), __DIR__ . '/service.wsdl');
foreach ($client->__getFunctions() ?? [] as $signature) {
    echo $signature, "\n";
}

int sum(int $a, int $b)

Список полезен для быстрой диагностики имени и порядка аргументов, но не заменяет документацию ограничений типов и предметных ошибок. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$client = new SoapClient(null, ['location' => 'http://local.invalid', 'uri' => 'urn:manual']);
echo $client->__getFunctions() === null ? "no WSDL prototypes\n" : "prototypes found\n";

no WSDL prototypes

В non-WSDL mode PHP не может вывести список удалённых операций: договор должен храниться в спецификации приложения. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';
$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '0'), __DIR__ . '/service.wsdl');
$types = $client->__getTypes() ?? [];
echo str_contains($types[0], 'struct Order') ? "Order type\n" : "other type\n";
echo str_contains($types[0], 'string status') ? "status: string\n" : "status missing\n";

Order type
status: string

Тип помогает понять форму объекта ответа до var_dump реального заказа. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$client = new SoapClient(null, ['location' => 'http://local.invalid', 'uri' => 'urn:manual']);
var_export($client->__getTypes());
echo "\n";

NULL

null — ожидаемая граница режима, а не сетевой сбой. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';
$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '7'));
$client->__soapCall('sum', [new SoapParam(3, 'a'), new SoapParam(4, 'b')]);
$xml = $client->__getLastRequest();
echo is_string($xml) && str_contains($xml, '<ns1:sum>') ? "sum envelope\n" : "missing\n";
echo is_string($xml) && str_contains($xml, '>4</b>') ? "b=4\n" : "b missing\n";

sum envelope
b=4

Вместо угадывания структуры сравниваем фактический Envelope с документацией поставщика. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';
$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '3'), null, ['trace' => false]);
$client->__soapCall('sum', [new SoapParam(1, 'a'), new SoapParam(2, 'b')]);
echo $client->__getLastRequest() === null ? "trace is off\n" : "request retained\n";

trace is off

Transport был выполнен, но диагностическая копия не сохранена. Это отдельная настройка, а не ошибка вызова. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';
$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '7'));
$value = $client->__soapCall('sum', [new SoapParam(3, 'a'), new SoapParam(4, 'b')]);
$xml = $client->__getLastResponse();
echo $value, "\n";
echo is_string($xml) && str_contains($xml, '>7</return>') ? "raw return=7\n" : "raw missing\n";

7
raw return=7

Так находят границу: XML правильный, а PHP mapping неожиданен — значит исследуют WSDL/classmap/typemap, а не сеть. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';
$client = new ManualMockSoapClient(manualSoapFault('Server', 'Stock unavailable'), null, ['exceptions' => false]);
$result = $client->__soapCall('reserve', [['sku' => 'A-1']]);
echo is_soap_fault($result) ? "fault object\n" : "result object\n";
echo str_contains((string) $client->__getLastResponse(), '<SOAP-ENV:Fault>') ? "fault XML\n" : "no fault XML\n";

fault object
fault XML

Raw XML помогает подтвердить, что Fault пришёл от transport double/сервиса; приложение всё равно работает со структурированным SoapFault. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$url = getenv('SOAP_TEST_URL') ?: throw new RuntimeException('SOAP_TEST_URL missing');
$client = new SoapClient(null, ['location' => $url, 'uri' => 'urn:manual', 'trace' => true]);
$client->__soapCall('sum', [new SoapParam(2, 'a'), new SoapParam(3, 'b')]);
$headers = (string) $client->__getLastRequestHeaders();
echo str_starts_with($headers, 'POST ') ? "POST\n" : "method differs\n";
echo stripos($headers, 'Content-Type: text/xml') !== false ? "SOAP 1.1 content type\n" : "content type differs\n";
echo stripos($headers, 'SOAPAction:') !== false ? "SOAPAction present\n" : "SOAPAction missing\n";

POST
SOAP 1.1 content type
SOAPAction present

Выполняется настоящий HTTP-запрос к одноразовому loopback-серверу, поэтому заголовки созданы transport ext/soap. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; HTTP endpoint — одноразовый loopback-сервер, без внешней сети.

<?php
declare(strict_types=1);

$url = getenv('SOAP_TEST_URL') ?: throw new RuntimeException('SOAP_TEST_URL missing');
$client = new SoapClient(null, [
    'location' => $url,
    'uri' => 'urn:manual',
    'trace' => true,
    'user_agent' => 'ManualService/1.0',
]);
$client->__soapCall('greet', [new SoapParam('Анна', 'name')]);
$headers = (string) $client->__getLastRequestHeaders();
echo stripos($headers, 'User-Agent: ManualService/1.0') !== false ? "agent ok\n" : "agent missing\n";

agent ok

User-Agent помогает поставщику различать интеграции; он не должен содержать секреты или пользовательский ввод. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; HTTP endpoint — одноразовый loopback-сервер, без внешней сети.

<?php
declare(strict_types=1);

$url = getenv('SOAP_TEST_URL') ?: throw new RuntimeException('SOAP_TEST_URL missing');
$client = new SoapClient(null, ['location' => $url, 'uri' => 'urn:manual', 'trace' => true]);
$client->__soapCall('sum', [new SoapParam(2, 'a'), new SoapParam(3, 'b')]);
$headers = (string) $client->__getLastResponseHeaders();
echo str_contains($headers, '200 OK') ? "HTTP 200\n" : "status differs\n";
echo stripos($headers, 'X-Manual-Server: loopback') !== false ? "server marker\n" : "marker missing\n";

HTTP 200
server marker

HTTP status/header диагностируют gateway и transport; предметный SOAP Fault при этом способен прийти и с HTTP 200. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; HTTP endpoint — одноразовый loopback-сервер, без внешней сети.

<?php
declare(strict_types=1);

$base = getenv('SOAP_TEST_URL') ?: throw new RuntimeException('SOAP_TEST_URL missing');
$client = new SoapClient(null, [
    'location' => $base . '?persistence=1',
    'uri' => 'urn:manual',
    'trace' => true,
]);
echo $client->__soapCall('increment', []), "\n";
$headers = (string) $client->__getLastResponseHeaders();
echo stripos($headers, 'Set-Cookie: PHPSESSID=') !== false ? "session issued\n" : "session missing\n";

1
session issued

Пример показывает transport state, необходимый SOAP_PERSISTENCE_SESSION. В production session cookie защищают Secure/HttpOnly/SameSite там, где это применимо. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; HTTP endpoint — одноразовый loopback-сервер, без внешней сети.

<?php
declare(strict_types=1);

$client = new SoapClient(null, ['location' => 'http://local.invalid', 'uri' => 'urn:manual']);
$client->__setCookie('region', 'spb');
$client->__setCookie('region', 'msk');
echo $client->__getCookies()['region'][0], "\n";
$client->__setCookie('empty', '');
echo array_key_exists('empty', $client->__getCookies()) && $client->__getCookies()['empty'][0] === '' ? "empty string kept\n" : "empty string lost\n";
$client->__setCookie('region', null);
echo array_key_exists('region', $client->__getCookies()) ? "kept\n" : "deleted\n";

msk
empty string kept
deleted

Повторная установка меняет значение. Пустая строка — настоящее сохранённое значение; только null или пропущенный второй аргумент удаляет cookie. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$url = getenv('SOAP_TEST_URL') ?: throw new RuntimeException('SOAP_TEST_URL missing');
$client = new SoapClient(null, ['location' => $url, 'uri' => 'urn:manual']);
$client->__setCookie('manual_session', 'request-42');
echo $client->__soapCall('readManualCookie', []), "\n";

request-42

Loopback-сервис читает обычный HTTP Cookie. Если договор требует SOAP Header, __setCookie — не тот инструмент. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; HTTP endpoint — одноразовый loopback-сервер, без внешней сети.

<?php
declare(strict_types=1);

$client = new SoapClient(null, ['location' => 'https://primary.example.test/soap', 'uri' => 'urn:manual']);
$old = $client->__setLocation('https://backup.example.test/soap');
echo "old: ", $old, "\n";
$beforeEmpty = $client->__setLocation('');
echo "empty cleared: ", $beforeEmpty, "\n";
echo $client->__setLocation('https://next.example.test/soap') === null ? "after empty: no override\n" : "after empty: override remained\n";
$beforeNull = $client->__setLocation(null);
echo "null cleared: ", $beforeNull, "\n";
echo $client->__setLocation('https://last.example.test/soap') === null ? "after null: no override\n" : "after null: override remained\n";

old: https://primary.example.test/soap
empty cleared: https://backup.example.test/soap
after empty: no override
null cleared: https://next.example.test/soap
after null: no override

И пустая строка, и null очищают location override. WSDL-клиент после очистки снова берёт endpoint из WSDL; у non-WSDL клиента fallback нет, поэтому до запроса нужно снова задать location или передать per-call option. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$url = getenv('SOAP_TEST_URL') ?: throw new RuntimeException('SOAP_TEST_URL missing');
$client = new SoapClient(null, ['location' => 'http://127.0.0.1:1/unavailable', 'uri' => 'urn:manual']);
$previous = $client->__setLocation($url);
echo str_contains((string) $previous, ':1/') ? "old endpoint recorded\n" : "old endpoint differs\n";
echo $client->__soapCall('sum', [new SoapParam(8, 'a'), new SoapParam(9, 'b')]), "\n";

old endpoint recorded
17

Failover выполняется до запроса; не нужно ждать заведомо недоступный адрес в учебном опыте. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; HTTP endpoint — одноразовый loopback-сервер, без внешней сети.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';
$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '3'));
$client->__setSoapHeaders(new SoapHeader('urn:meta', 'RequestId', 'req-1'));
$client->__soapCall('sum', [new SoapParam(1, 'a'), new SoapParam(2, 'b')]);
echo str_contains($client->seenRequest, 'req-1') ? "header sent\n" : "missing\n";
$client->__setSoapHeaders(null);
$client->__soapCall('sum', [new SoapParam(1, 'a'), new SoapParam(2, 'b')]);
echo str_contains($client->seenRequest, 'req-1') ? "header kept\n" : "header cleared\n";

header sent
header cleared

Метод заменяет весь default header set. Null удаляет прежние значения для будущих вызовов. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/mock-soap.php';
$client = new ManualMockSoapClient(manualSoapResponse('sum', 'int', '3'));
$ok = $client->__setSoapHeaders([
    new SoapHeader('urn:meta', 'RequestId', 'req-42'),
    new SoapHeader('urn:meta', 'Locale', 'ru-RU'),
]);
$client->__soapCall('sum', [new SoapParam(1, 'a'), new SoapParam(2, 'b')]);
echo $ok ? "headers accepted\n" : "headers rejected\n";
echo str_contains($client->seenRequest, 'req-42') && str_contains($client->seenRequest, 'ru-RU') ? "both sent\n" : "missing value\n";

headers accepted
both sent

Массив нужен для нескольких sibling элементов Header, а не для произвольного вложенного XML. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';

function sum(int $a, int $b): int { return $a + $b; }
$server = new SoapServer(null, ['uri' => 'urn:manual']);
$server->addFunction('sum');
$response = manualHandle($server, manualSoapRequest('sum', ['a' => 6, 'b' => 7]));
echo manualXmlValue($response), "\n";

13

Non-WSDL серверу обязательно сообщают target namespace. Строка request передана явно, поэтому пример работает в CLI без HTTP. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';

function sum(int $a, int $b): int { return $a + $b; }
$server = new SoapServer(__DIR__ . '/service.wsdl', ['cache_wsdl' => WSDL_CACHE_NONE]);
$server->addFunction('sum');
$response = manualHandle($server, manualSoapRequest('sum', ['a' => 10, 'b' => 5]));
echo manualXmlValue($response), "\n";

15

WSDL задаёт operation/messages/binding; PHP-функция реализует поведение. В production контракт версионируют и проверяют на совместимость до deploy. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$server = new SoapServer(null, ['uri' => 'urn:manual']);
function quoteTotal(int $quantity, int $price): int { return $quantity * $price; }
$server->addFunction('quoteTotal');
echo implode(', ', $server->getFunctions()), "\n";

quoteTotal

Allowlist делает поверхность сервиса явной: локальные вспомогательные функции наружу не выходят. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

function reserveStock(string $sku): string { return 'reserved:' . $sku; }
function releaseStock(string $sku): string { return 'released:' . $sku; }
$server = new SoapServer(null, ['uri' => 'urn:manual']);
$server->addFunction(['reserveStock', 'releaseStock']);
$names = $server->getFunctions();
sort($names);
echo implode(' | ', $names), "\n";

releaseStock | reserveStock

С PHP 8.4 int/SOAP_FUNCTIONS_ALL deprecated: массив имён безопаснее и показывает намерение. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';

function ping(): string
{
    $GLOBALS['manualServer']->addSoapHeader(new SoapHeader('urn:meta', 'RequestId', 'req-42'));
    return 'pong';
}
$manualServer = new SoapServer(null, ['uri' => 'urn:manual']);
$manualServer->addFunction('ping');
$xml = manualHandle($manualServer, manualSoapRequest('ping', []));
echo manualXmlValue($xml, 'RequestId'), "\n";
echo manualXmlValue($xml), "\n";

req-42
pong

Header добавляется во время текущего handle. Он отделён от бизнес-return и подходит для correlation metadata. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';

function checkLimit(): string
{
    $GLOBALS['manualServer']->addSoapHeader(new SoapHeader('urn:meta', 'RateLimitRemaining', 9));
    return 'accepted';
}
$manualServer = new SoapServer(null, ['uri' => 'urn:manual']);
$manualServer->addFunction('checkLimit');
$xml = manualHandle($manualServer, manualSoapRequest('checkLimit', []));
echo manualXmlValue($xml, 'RateLimitRemaining'), "\n";
echo manualXmlValue($xml), "\n";

9
accepted

Метаданные не приходится добавлять в каждую предметную response structure, если это согласовано SOAP-контрактом. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';

function reserve(string $sku): string
{
    $GLOBALS['manualServer']->fault('Client', 'Нет остатка', 'urn:shop', ['sku' => $sku]);
    return 'unreachable';
}
$manualServer = new SoapServer(null, ['uri' => 'urn:manual', 'encoding' => 'UTF-8']);
$manualServer->addFunction('reserve');
ob_start();
register_shutdown_function(static function (): void {
    $xml = (string) ob_get_clean();
    echo manualXmlValue($xml, 'faultcode'), "\n";
    echo manualXmlValue($xml, 'faultstring'), "\n";
});
$manualServer->handle(manualSoapRequest('reserve', ['sku' => 'OUT']));

SOAP-ENV:Client
Нет остатка

Метод сразу формирует Fault текущего request; код после него не должен считаться продолжением успешной операции. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';

function reject(): string
{
    $GLOBALS['manualServer']->fault('Sender', 'Неверный заказ', '', null, '', 'ru');
    return 'unreachable';
}
$manualServer = new SoapServer(null, ['uri' => 'urn:manual', 'soap_version' => SOAP_1_2, 'encoding' => 'UTF-8']);
$manualServer->addFunction('reject');
$request = str_replace(
    'http://schemas.xmlsoap.org/soap/envelope/',
    'http://www.w3.org/2003/05/soap-envelope',
    manualSoapRequest('reject', []),
);
ob_start();
register_shutdown_function(static function (): void {
    $xml = (string) ob_get_clean();
    echo str_contains($xml, 'xml:lang="ru"') ? "lang=ru\n" : "lang missing\n";
    echo manualXmlValue($xml, 'Text'), "\n";
});
$manualServer->handle($request);

lang=ru
Неверный заказ

Параметр lang добавлен в PHP 8.5 для соответствия SOAP 1.2. Код Fault для реального сервиса сверяют со спецификацией. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

function ping(): string { return 'pong'; }
function health(): string { return 'ok'; }
$server = new SoapServer(null, ['uri' => 'urn:manual']);
$server->addFunction(['ping', 'health']);
$names = $server->getFunctions();
sort($names);
echo implode(', ', $names), "\n";

health, ping

Такой smoke-check подтверждает allowlist до запуска HTTP endpoint. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

final class CatalogService
{
    public function find(string $sku): string { return $sku; }
    public function price(string $sku): int { return 100; }
    private function secret(): string { return 'hidden'; }
}
$server = new SoapServer(null, ['uri' => 'urn:manual']);
$server->setObject(new CatalogService());
$names = $server->getFunctions();
sort($names);
echo implode(', ', $names), "\n";

find, price

getFunctions учитывает setObject так же, как setClass: внешними становятся публичные методы; private helper не экспортируется. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';
function ping(): string { return 'pong'; }
$server = new SoapServer(null, ['uri' => 'urn:manual', 'trace' => true]);
$server->addFunction('ping');
$output = manualHandle($server, manualSoapRequest('ping', []));
$saved = $server->__getLastResponse();
echo is_string($saved) && $saved === $output ? "same response\n" : "different\n";
echo manualXmlValue($output), "\n";

same response
pong

PHP 8.4+ позволяет читать именно response текущего server object при trace=true. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';
function ping(): string { return 'pong'; }
$server = new SoapServer(null, ['uri' => 'urn:manual', 'trace' => false]);
$server->addFunction('ping');
manualHandle($server, manualSoapRequest('ping', []));
echo $server->__getLastResponse() === null ? "trace is off\n" : "response retained\n";

trace is off

Отсутствие копии не означает, что ответ не сформирован: trace — отдельная диагностическая опция. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';
function multiply(int $a, int $b): int { return $a * $b; }
$server = new SoapServer(null, ['uri' => 'urn:manual']);
$server->addFunction('multiply');
$request = manualSoapRequest('multiply', ['a' => 6, 'b' => 7]);
$response = manualHandle($server, $request);
echo manualXmlValue($response), "\n";

42

Явная строка удобна в unit/contract test: видны входной Envelope, выбранный обработчик и точный результат. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$url = getenv('SOAP_TEST_URL') ?: throw new RuntimeException('SOAP_TEST_URL missing');
$client = new SoapClient(null, ['location' => $url, 'uri' => 'urn:manual']);
echo $client->__soapCall('greet', [new SoapParam('Мир', 'name')]), "\n";

Здравствуйте, Мир

В server fixture вызывается handle() без аргумента: ext/soap читает реальный HTTP request body, отправленный SoapClient. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; HTTP endpoint — одноразовый loopback-сервер, без внешней сети.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';
final class DeliveryService
{
    public function estimate(string $city): string { return $city . ': 2 дня'; }
}
$server = new SoapServer(null, ['uri' => 'urn:manual']);
$server->setClass(DeliveryService::class);
$response = manualHandle($server, manualSoapRequest('estimate', ['city' => 'Тула']));
echo manualXmlValue($response), "\n";

Тула: 2 дня

Методы одного предметного сервиса и его зависимости собраны в объекте, а не разбросаны по глобальным функциям. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';
final class PriceService
{
    public function __construct(private string $currency, private int $rate) {}
    public function quote(int $units): string { return ($units * $this->rate) . ' ' . $this->currency; }
}
$server = new SoapServer(null, ['uri' => 'urn:manual']);
$server->setClass(PriceService::class, 'RUB', 125);
$response = manualHandle($server, manualSoapRequest('quote', ['units' => 3]));
echo manualXmlValue($response), "\n";

375 RUB

Variadic args идут в конструктор при создании handler object. Секреты лучше передавать через настроенный dependency container, а не hardcode. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';
final class WarehouseService
{
    public function __construct(private string $warehouse) {}
    public function locate(string $sku): string { return $sku . '@' . $this->warehouse; }
}
$handler = new WarehouseService('MSK-1');
$server = new SoapServer(null, ['uri' => 'urn:manual']);
$server->setObject($handler);
$response = manualHandle($server, manualSoapRequest('locate', ['sku' => 'A-17']));
echo manualXmlValue($response), "\n";

A-17@MSK-1

Объект можно заранее собрать с проверенной конфигурацией и зависимостями. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

require __DIR__ . '/soap-server-helper.php';
final class StatusStub
{
    public function __construct(private string $status) {}
    public function orderStatus(int $id): string { return $id . ':' . $this->status; }
}
$server = new SoapServer(null, ['uri' => 'urn:manual']);
$server->setObject(new StatusStub('ready'));
$response = manualHandle($server, manualSoapRequest('orderStatus', ['id' => 731]));
echo manualXmlValue($response), "\n";

731:ready

Contract test управляет состоянием handler object без БД/банка, а сериализацию оставляет настоящему SoapServer. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; внешняя сеть и рабочие сервисы не используются.

<?php
declare(strict_types=1);

$base = getenv('SOAP_TEST_URL') ?: throw new RuntimeException('SOAP_TEST_URL missing');
$client = new SoapClient(null, ['location' => $base . '?persistence=request', 'uri' => 'urn:manual']);
echo $client->__soapCall('increment', []), "\n";
echo $client->__soapCall('increment', []), "\n";

1
1

SOAP_PERSISTENCE_REQUEST — значение по умолчанию: каждый HTTP request получает новый CounterService. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; HTTP endpoint — одноразовый loopback-сервер, без внешней сети.

<?php
declare(strict_types=1);

$base = getenv('SOAP_TEST_URL') ?: throw new RuntimeException('SOAP_TEST_URL missing');
$client = new SoapClient(null, ['location' => $base . '?persistence=session', 'uri' => 'urn:manual']);
echo $client->__soapCall('increment', []), "\n";
echo $client->__soapCall('increment', []), "\n";

final class PersistenceProbe {}
$classServer = new SoapServer(null, ['uri' => 'urn:manual']);
$classServer->setClass(PersistenceProbe::class);
try {
    $classServer->setPersistence(999);
} catch (ValueError $error) {
    echo "invalid mode: ValueError\n";
}
$functionServer = new SoapServer(null, ['uri' => 'urn:manual']);
try {
    $functionServer->setPersistence(SOAP_PERSISTENCE_REQUEST);
} catch (Error $error) {
    echo "function mode: Error\n";
}

1
2
invalid mode: ValueError
function mode: Error

SOAP_PERSISTENCE_SESSION сериализует handler object в PHP session; затем пример фиксирует ValueError неверного mode в class mode и Error попытки persistence в function mode. Пример выполнен на локальном PHP 8.5.11 с process-only ext/soap; HTTP endpoint — одноразовый loopback-сервер, без внешней сети.