wz-opensdk / wz-opensdk

0.1.1 2026-09-09 08:09 UTC

Requires

• php: >=8.1
• guzzlehttp/guzzle: ^7.8
• psr/log: ^3.0

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

Published on Packagist.org on 2026-09-09 08:09 UTC

README

万桩开放平台 PHP SDK。覆盖 Apifox 项目 wz-open 中文目录下的公开 API（设备、充电、续费、开票、回调日志）。inner/* 内部接口不在本 SDK 中。SDK 只做 client，不解析平台推送到合作方的入站回调。

Composer 坐标：wz-opensdk/wz-opensdk。PHP 8.1+。

安装

composer require wz-opensdk/wz-opensdk:^0.1
# 请装 0.1.1+。Packagist 已锁定 0.1.0 的 git 引用，不要指定 0.1.0

本地开发可用 Gitee 仓库：

{
  "require": {
    "wz-opensdk/wz-opensdk": "*@dev"
  },
  "repositories": [
    { "type": "vcs", "url": "https://gitee.com/wz-open-platform/wz-opensdk-php.git" }
  ]
}

快速开始

use Wanzhuangkj\OpenSdk\Device\DeviceNumRequest;
use Wanzhuangkj\OpenSdk\WzOpenClient;

$client = WzOpenClient::builder()
    ->endpoint(getenv('WZ_OPEN_ENDPOINT'))
    ->appId(getenv('WZ_OPEN_APP_ID'))
    ->appSecret(getenv('WZ_OPEN_APP_SECRET'))
    ->build();

$device = $client->device()->findOne(new DeviceNumRequest('18000001'));

也可 WzOpenClient::fromEnv()（读 WZ_OPEN_ENDPOINT / WZ_OPEN_APP_ID / WZ_OPEN_APP_SECRET）。

按域调用，方法不堆在 WzOpenClient 上：

• $client->device() 设备绑定、计费模式、状态、在线日志
• $client->charge()->start / stop
• $client->renew()
• $client->invoice()
• $client->callback()->log / retryFinishOrder

默认请求超时 10s。

签名

SDK 按接入指引自动加 app_id、timestamp、sign（HMAC-SHA256 大写 hex）。调用方不要自己拼签，也不要传 company_id。金额单位为分。

契约以开放平台文档为准（汽车桩 saveMode/getMode 在 SDK 中拆成独立方法；/open/device/setting/sync 属于 inner，本 SDK 不实现）。公开能力合计 40 条出站 API。

日志

使用 PSR-3。库内默认 NullLogger。覆盖：

WzOpenClient::builder()
    ->logger($psrLogger)
    ...

成功请求的 info 日志会带 method、path；响应头有 X-B3-TraceId 时再带 traceId。失败时同一字段出现在 error 日志里，并可从 WzOpenApiException::getTraceId() 读取。

HTTP

可配 timeout（默认 10s）、retryCount（失败重试且每次重签）、retryWait、userAgent、proxyUrl，或直接传入 Guzzle ClientInterface。

开发

composer install
./vendor/bin/phpunit
# 或 make test

现网验证（需要凭证）：

export WZ_OPEN_ENDPOINT=...
export WZ_OPEN_APP_ID=...
export WZ_OPEN_APP_SECRET=...
make verify