你是否也曾遇到过这样的场景？当SOAP服务的文档摆在你面前，里面充斥着WSSE、WSA、X.509证书、XML数字签名、时间戳等各种术语，你是不是瞬间感到一阵眩晕？我当时就是这样。
尝试过最初的方案，是手动拼接XML，或者使用一些老旧的SOAP客户端，但很快就遇到了瓶颈：
- 复杂且易错的XML操作： WSSE头部的结构非常复杂，包含各种命名空间、元素顺序、时间戳、二进制安全令牌、签名信息等。手动构建或修改这些XML字符串，就像在走钢丝，一个字符的错误都可能导致服务拒绝。
- 证书和密钥管理： 数字签名需要用到私钥和公钥证书。如何安全地加载、使用这些密钥，并正确地将它们嵌入到XML中，成了一个大难题。
- 调试困难： 当请求被拒绝时，SOAP服务通常只会返回一个模糊的错误信息，很难定位是WSSE头部的结构问题、签名问题，还是证书配置问题。
- 缺乏灵活性： 不同的SOAP服务可能有不同的WSSE配置要求（例如，签名算法、摘要算法、KeyIdentifier类型）。手动方案很难快速适应这些变化。
眼看项目进度受阻，我开始寻找一个更现代、更健壮的解决方案。这时，Composer的强大生态再次展现了它的魅力。
Composer在线学习地址：学习地址
立即学习“PHP免费学习笔记（深入）”；
我发现了 php-soap/psr18-wsse-middleware 这个库，它简直是我的救星！这个包是为基于PSR-18的HTTP SOAP传输而设计的中间件，它能将复杂的WSSE和WSA安全逻辑封装起来，让我们以更简洁、更PHP友好的方式进行配置。
核心思想：中间件与可配置条目
php-soap/psr18-wsse-middleware 的核心在于它作为一个PSR-18 HTTP客户端的中间件，可以轻松地插入到你的HTTP请求流程中。它将WSSE的各种安全特性抽象为一系列可配置的“条目（Entry）”，例如：Username、Timestamp、BinarySecurityToken、Signature、Encryption 等。你只需要根据SOAP服务的具体要求，组合这些条目即可。
如何使用它解决问题？
首先，通过Composer安装它：
composer require php-soap/psr18-wsse-middleware
这个包通常与 php-soap/psr18-transport 配合使用，后者提供了PSR-18标准的SOAP传输能力。
1. 添加WS-Addressing (WSA) 头
如果你的SOAP服务需要WSA头（例如，Action、To 等），你可以使用 WsaMiddleware 或 WsaMiddleware2005。
use Http\Client\Common\PluginClient;
use Soap\Psr18Transport\Psr18Transport;
use Soap\Psr18WsseMiddleware\WsaMiddleware;
use Soap\Psr18WsseMiddleware\WsaMiddleware2005;
use GuzzleHttp\Client as GuzzleClient; // 假设你使用Guzzle作为PSR-18客户端
$psr18Client = new GuzzleClient(); // 你的PSR-18兼容HTTP客户端
$transport = Psr18Transport::createForClient(
new PluginClient($psr18Client, [
new WsaMiddleware(), // 或 new WsaMiddleware2005()，取决于WSA版本
])
);
// 接下来，你可以使用这个 $transport 对象来发送SOAP请求
// ...通过简单的实例化和添加到插件客户端，WSA头就自动注入到你的SOAP请求中了，省去了手动构建XML的麻烦。
2. 实现WS-Security (WSSE)
这才是真正的“大头”。WsseMiddleware 允许你配置各种WSSE条目。它的设计理念非常棒，如果你在SoapUI中配置过WS-Security，你会发现这里的PHP代码结构与SoapUI的UI配置非常相似，这极大地降低了学习成本。
示例一：添加用户名和密码认证
这是最常见的WSSE需求之一。
use Soap\Psr18WsseMiddleware\WsseMiddleware;
use Soap\Psr18WsseMiddleware\WSSecurity\Entry;
use Http\Client\Common\PluginClient;
use Soap\Psr18Transport\Psr18Transport;
use GuzzleHttp\Client as GuzzleClient;
$user = 'myUsername';
$password = 'myPassword';
$wsseMiddleware = new WsseMiddleware(
outgoing: [
(new Entry\Username($user))
->withPassword($password)
->withDigest(false), // 如果密码不需要摘要，设置为false
new Entry\Timestamp(60), // 添加一个有效期60秒的时间戳
]
);
$transport = Psr18Transport::createForClient(
new PluginClient(new GuzzleClient(), [
$wsseMiddleware,
])
);
// 使用 $transport 发送SOAP请求，WSSE头会自动添加几行代码，就完成了复杂的用户名密码和时间戳注入，比手动拼接XML要清晰和安全得多。
示例二：使用X.509证书对请求进行数字签名
这是我遇到的最棘手的问题之一。服务要求使用PKCS12证书进行签名。这个库提供了 KeyStore 类来管理密钥和证书。
use Soap\Psr18WsseMiddleware\WsseMiddleware;
use Soap\Psr18WsseMiddleware\WSSecurity\Entry;
use Soap\Psr18WsseMiddleware\WSSecurity\KeyStore\Certificate;
use Soap\Psr18WsseMiddleware\WSSecurity\KeyStore\Key;
use Soap\Psr18WsseMiddleware\WSSecurity\KeyIdentifier;
use Soap\Psr18WsseMiddleware\WSSecurity\SignatureMethod;
use Soap\Psr18WsseMiddleware\WSSecurity\DigestMethod;
use Http\Client\Common\PluginClient;
use Soap\Psr18Transport\Psr18Transport;
use GuzzleHttp\Client as GuzzleClient;
// 假设你的私钥和公钥证书文件
$privateKeyFile = 'path/to/security_token.priv'; // 从PKCS12转换出的私钥
$publicKeyFile = 'path/to/security_token.pub'; // 从PKCS12转换出的公钥证书
$passphrase = 'your_key_passphrase';
$privKey = Key::fromFile($privateKeyFile)->withPassphrase($passphrase);
$pubKey = Certificate::fromFile($publicKeyFile);
$wsseMiddleware = new WsseMiddleware(
outgoing: [
new Entry\Timestamp(60),
new Entry\BinarySecurityToken($pubKey), // 将公钥证书作为二进制安全令牌
(new Entry\Signature(
$privKey,
new KeyIdentifier\BinarySecurityTokenIdentifier() // 指定签名时使用二进制安全令牌作为标识
))
->withSignatureMethod(SignatureMethod::RSA_SHA256) // 签名算法
->withDigestMethod(DigestMethod::SHA256) // 摘要算法
->withSignAllHeaders(true) // 签名所有SOAP头
->withSignBody(true) // 签名SOAP Body
]
);
$transport = Psr18Transport::createForClient(
new PluginClient(new GuzzleClient(), [
$wsseMiddleware,
])
);
// 现在，你的SOAP请求会自动包含签名和证书信息这段代码清晰地展示了如何加载密钥、配置签名算法、摘要算法以及签名范围。它将所有复杂性封装在 Entry\Signature 对象中，我们只需提供正确的参数，大大降低了出错的概率。
示例三：加密和解密敏感数据
某些服务甚至要求对SOAP请求或响应中的敏感部分进行加密。php-soap/psr18-wsse-middleware 也提供了 Entry\Encryption 和 Entry\Decryption。
// ... (密钥和证书加载与签名类似)
$wsseMiddleware = new WsseMiddleware(
outgoing: [
// ... 其他如Timestamp, BinarySecurityToken, Signature 条目
(new Entry\Encryption(
$signKey, // 用于加密的公钥证书
new KeyIdentifier\X509SubjectKeyIdentifier($signKey)
))
->withKeyEncryptionMethod(KeyEncryptionMethod::RSA_OAEP_MGF1P)
->withDataEncryptionMethod(DataEncryptionMethod::AES256_CBC)
],
incoming: [
new Entry\Decryption($privKey) // 用于解密响应的私钥
]
);
// ...注意：官方文档提到，加密功能在底层库中存在一个已知bug，并提供了Composer补丁的解决方案。这体现了在实际使用中需要关注细节和社区支持。
总结其优势和实际应用效果
使用 php-soap/psr18-wsse-middleware 之后，我深刻体会到了它带来的巨大优势：
- 告别XML噩梦： 最直接的感受就是再也不用手动去拼接和解析复杂的WSSE/WSA XML头了。库内部处理了所有细节，大大减少了出错的可能性。
-
开发效率大幅提升： 以前需要花费数天甚至一周来调试和解决的SOAP安全认证问题，现在通过阅读文档和配置几个
Entry对象，往往只需几个小时就能搞定。 -
代码可读性和可维护性增强： 清晰的面向对象API，让WSSE配置逻辑一目了然。当服务方调整安全要求时，我们只需修改或添加相应的
Entry，而不是修改大段的XML字符串。 - 高度灵活性： 它支持多种WSSE/WSA标准和算法，无论是用户名密码、数字签名、时间戳、SAML断言，还是加密解密，都能轻松应对。这使得它能够适应各种复杂的SOAP服务集成场景。
- 现代化集成： 基于PSR-18 HTTP客户端，使得它可以与现代PHP生态中的HTTP客户端（如Guzzle）无缝集成，符合现代PHP开发的最佳实践。
在我的项目中，通过引入 php-soap/psr18-wsse-middleware，我们成功地与遗留的SOAP服务建立了安全、稳定的连接，并按时完成了项目交付。它不仅解决了技术难题，更重要的是，将开发者从繁琐且易错的SOAP安全配置中解放出来，让我们能够专注于业务逻辑的实现。
如果你也在为SOAP服务的WSSE/WSA安全认证而烦恼，强烈推荐你尝试一下 php-soap/psr18-wsse-middleware。它将是你在SOAP集成之路上的得力助手！
