snapWONDERS/snapWONDERS-SDK-PHP
GitHub: snapWONDERS/snapWONDERS-SDK-PHP
snapWONDERS API 的官方 PHP 客户端库，封装了隐写术、媒体取证分析和格式转换三大功能及完整的任务编排流程。
Stars: 0 | Forks: 0
snapWONDERS — 暴露隐藏之物。隐藏您之所拥。
# snapwonders/sdk — snapWONDERS API 的 PHP 客户端
snapWONDERS API 的官方 PHP 客户端：隐写术、取证媒体分析和格式转换。该客户端封装了可恢复的 TUS 上传以及“会话 → 任务 → 轮询 → 下载”的编排流程，因此只需几行代码即可完成一整套任务。
所有 snapWONDERS API 服务均可通过 Clearnet / **Web** 以及暗网 **Tor** 和 **I2P** 访问。
# 安装与设置
## snapWONDERS API 密钥
在开始之前，您需要一个 snapWONDERS API 密钥：
* 在 [snapWONDERS 注册](https://snapwonders.com/sign-up) 注册并创建一个帐户。如果您希望通过 Tor 或 I2P 创建帐户，则可以通过 Tor 或 I2P 门户访问 snapWONDERS 来实现。有关暗网链接，请访问[安全浏览](https://snapwonders.com/browsing-safely)。
* 在您的帐户设置下，生成一个 API 密钥。新密钥以 `sw_` 开头。它会作为 `X-Api-Key` 标头在每次请求中发送 —— 请妥善保管。
## 要求
PHP 8.2+，并带有 `curl` 和 `json` 扩展（两者均为标准配置）。无其他运行时依赖。
## 安装软件包
```
composer require snapwonders/sdk # once published
```
# 快速开始
```
status()); // no key needed for status
// Hide a secret inside a cover image (the last file is the cover).
$job = $client->stego->hide(['secret.png', 'cover.jpg'], password: 'Str0ng!Pass');
foreach ($job->results() as $result) {
$result->download('out/'); // "out/" is a directory — the server filename is kept
}
// Reveal it again.
$job = $client->stego->reveal('out/cover-share.avif', password: 'Str0ng!Pass');
$job->results()[0]->download('recovered/');
```
`$client->analyse`（取证分析）和 `$client->convert`（媒体转换）遵循相同的结构 —— 一次调用进入，结果输出：
```
// Forensic analysis — grade each file A–F, collect the overlay assets it produced.
$job = $client->analyse->run(['photo.jpg'], options: ['face_detection' => true]);
foreach ($job->results() as $item) {
echo "{$item->filename} {$item->grade} faces={$item->faceCount}\n";
foreach ($item->assets as $asset) { // ELA map, face overlay, …
$asset->download('out/');
}
}
// Convert media — the image format key is `image_format` (jpeg/png/webp/avif/heic/jxl).
$job = $client->convert->run(['photo.png'], options: ['image_format' => 'webp']);
$job->results()[0]->download('out/');
```
想要自己控制每个阶段？分步调用的接口同样是公开的：
`createSession()` → `upload($path, $step)` → `waitForUploads()` → `startJob(...)` → `wait()` → `results()`。
# 示例
可运行的端到端示例位于 [`examples/`](examples/) —— 包括隐写术、取证分析和转换，每个都是一个自带示例图片的独立脚本：
```
composer install
export SNAPWONDERS_API_KEY=sw_your_key_here
php examples/hide_and_reveal.php # hide a file in an image, then reveal it
php examples/analyse.php # grade an image A–F + download overlay assets
php examples/convert.php # PNG → WebP
```
有关如何运行它们，请参见 [`examples/README.md`](examples/README.md)。
# 错误
SDK 引发的每个失败都是 `SnapWonders\Exception\SnapWondersException` 的类型化子类，因此您可以根据失败的类型进行分支处理，而无需检查 HTTP 状态码：
| 异常 | 引发条件 |
|-----------|-------------|
| `AuthException` | API 密钥缺失、格式错误、未知或已被吊销 |
| `ProRequiredException` | 在免费帐户上使用了 Pro 专属选项 |
| `SessionExpiredException` | 已超过 24 小时的上传会话窗口期 |
| `RateLimitException` | 被限速 —— 当服务器提供时附带 `retryAfter` |
| `MaintenanceException` | snapWONDERS 因维护而暂时不可用 —— 附带 `retryAfter` |
| `JobFailedException` | 任务以 `failed` 状态结束 —— 附带服务器的原因 |
| `TusUploadException` | 可恢复上传步骤失败 |
| `NetworkException` | 无法连接到 API |
| `ApiException` | 任何其他非 2xx 响应 |
# 运行测试
```
composer install
composer test # offline unit tests — no API key required
```
# 文档
有用的文档可以在以下位置找到：
* 交互式 Swagger UI 和完整的端点参考：
[snapWONDERS API](https://snapwonders.com/api)
* 循序渐进的集成指南：
[snapWONDERS 开发者](https://snapwonders.com/developers)
# 联系方式
## 关于安全问题
如果您发现了任何安全问题，请通过[联系 snapWONDERS](https://snapwonders.com/contact) 告知我们，并将主题设置为 **"SECURITY CONCERNS"**，同时提供有关您所发现问题的详细信息。如果您希望通过 Tor 或 I2P 联系，可以通过 Tor 或 I2P 门户访问 snapWONDERS。有关暗网链接，请访问[安全浏览](https://snapwonders.com/browsing-safely)。
## 关于常见问题和疑问
您的问题可能已经在[常见问题解答](https://snapwonders.com/faq)中得到解答。请务必先查看 FAQ 内容。否则，您可以通过[联系 snapWONDERS](https://snapwonders.com/contact) 与我们取得联系。
## 联系作者
使用此链接联系作者 [Kenneth Springer](https://kennethbspringer.au/)。
# 许可证
MIT — 版权所有 (c) 2026 Kenneth Springer @ snapWONDERS。请参见 [LICENSE](LICENSE)。
**适用范围。** MIT 许可证仅涵盖**此客户端库**。它不授予与其通信的 snapWONDERS API、服务、数据、模型或算法的任何权利 —— 这些都是**专有的**，并归 Kenneth Springer @ snapWONDERS 所有。此库仅向 API 发送 HTTP 请求；它不包含其任何实现内容。使用 API 需要有效的 API 密钥，并受 [snapWONDERS 服务条款](https://snapwonders.com/terms) 约束。
标签：API客户端, ffuf, OpenVAS, PHP, 媒体分析, 数字取证, 格式转换, 自动化脚本, 隐写术