README

面向企业微信的 PHP SDK（当前包含：应用消息 + 通讯录 + 身份与登录 + 回调事件 + 客户联系 + OA/审批 + 小程序 + 支付）。

安装

composer require workwexin/wecom

配置说明

$config = [
    "corps" => [
        "default" => [
            "corp_id" => "wx123",
            "apps" => [
                "default" => [
                    "agent_id" => 1000002,
                    "secret" => "app_secret"
                ]
            ]
        ]
    ],
    "cache" => [
        "path" => __DIR__ . "/runtime/cache",
        "ttl" => 7200
    ],
    "http" => [
        "timeout" => 5.0,
        "base_uri" => "https://qyapi.weixin.qq.com"
    ]
];

字段说明：

• corps：多企业配置，key 为企业别名
• corps.{corp}.corp_id：企业 ID
• corps.{corp}.apps：企业下的多个应用
• corps.{corp}.apps.{app}.agent_id：应用 AgentId
• corps.{corp}.apps.{app}.secret：应用 Secret
• cache.path：文件缓存目录（access_token 缓存）
• cache.ttl：默认缓存时间（秒）
• cache.instance：自定义缓存（需实现 Psr\SimpleCache\CacheInterface）
• http.timeout：HTTP 超时时间
• http.base_uri：企业微信 API 根地址
• http.client：自定义 HTTP 客户端（需实现 Psr\Http\Client\ClientInterface）
• http.retry.max_retries：最大重试次数（默认 0）
• http.retry.retry_delay_ms：重试间隔毫秒（默认 200）
• http.retry.retry_on_status：重试的 HTTP 状态码（默认 500/502/503/504）
• http.retry.retry_on_timeout：是否对超时重试（默认 true）
• http.retry.methods：允许重试的 HTTP 方法（默认 ["GET"]）
• logger：自定义日志（需实现 Psr\Log\LoggerInterface）
• corps.{corp}.callback.token：回调 Token
• corps.{corp}.callback.encoding_aes_key：回调 EncodingAESKey

快速开始

use WorkWeXin\WeCom;

$wecom = new WeCom($config, "default", "default");

$wecom->message()->send([
    "touser" => "userid1|userid2",
    "msgtype" => "text",
    "text" => ["content" => "Hello"]
]);

说明：agentid 如果未传，会从配置里的 agent_id 自动注入。

应用消息示例

$wecom->message()->sendText("你好", ["touser" => "userid1"]);
$wecom->message()->sendMarkdown("**加粗**内容", ["touser" => "userid1"]);
$wecom->message()->sendTextCard("标题", "描述", "https://example.com", ["touser" => "userid1"]);

任务卡片更新示例：

$wecom->message()->updateTaskCard("userid1|userid2", "task_id_xxx", "已完成");

通讯录 API

$wecom->contacts()->getUser("userid1");
$wecom->contacts()->listUsers(1, true);
$wecom->contacts()->createUser([
    "userid" => "userid1",
    "name" => "张三",
    "department" => [1]
]);
$wecom->contacts()->updateUser([
    "userid" => "userid1",
    "name" => "李四"
]);
$wecom->contacts()->deleteUser("userid1");

$wecom->contacts()->listDepartments();
$wecom->contacts()->createDepartment([
    "name" => "研发部",
    "parentid" => 1
]);
$wecom->contacts()->updateDepartment([
    "id" => 2,
    "name" => "技术部"
]);
$wecom->contacts()->deleteDepartment(2);

可用方法与字段说明

说明：以下为当前 SDK 可用方法（MVP：应用消息 + 通讯录）。

小程序：

支付：

客户联系：

OA 与审批：

身份与登录：

应用消息：

消息类型字段说明：

模板卡片字段说明：

通用字段：

对象字段：

说明：不同 card_type 对字段组合有要求，具体必填规则请以企业微信官方文档为准。 通讯录（成员）：

通讯录（部门）：

多企业/多应用

$wecom = new WeCom($config, "corp_a", "app1");
$wecomB = $wecom->forCorpApp("corp_b", "app2");

高级配置示例

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use WorkWeXin\WeCom;

$logger = new Logger("wecom");
$logger->pushHandler(new StreamHandler(__DIR__ . "/runtime/wecom.log"));

$config["logger"] = $logger;
$config["http"]["retry"] = [
    "max_retries" => 2,
    "retry_delay_ms" => 300,
    "retry_on_status" => [500, 502, 503, 504],
    "retry_on_timeout" => true
];

$wecom = new WeCom($config, "default", "default");

错误处理

SDK 会在接口返回 errcode != 0 时抛出异常：

use WorkWeXin\Exception\WeComException;

try {
    $wecom->message()->send([...]);
} catch (WeComException $e) {
    // $e->getErrCode() 获取 errcode
    // $e->getMessage() 获取 errmsg
}

通讯录扩展接口

批量/异步接口：

标签管理：

通讯录回调与变更同步

回调配置：

$config["corps"]["default"]["callback"] = [
    "token" => "your_token",
    "encoding_aes_key" => "your_encoding_aes_key_43_chars"
];

使用示例：

$crypto = $wecom->callback();
$plain = $crypto->verifyUrl($msgSignature, $timestamp, $nonce, $echoStr);
$event = $crypto->decryptMessage($msgSignature, $timestamp, $nonce, $postData);

回调事件分发示例：

$events = $wecom->callbackEvents();

$events->onEvent("change_contact", function (array $event, $service) {
    // 例如：成员/部门变更
    return null;
});

$events->onMessage("text", function (array $event, $service) {
    // 这里返回明文 XML，SDK 会自动加密
    return $service->buildTextReply($event, "已收到");
});

$reply = $events->dispatch($msgSignature, $timestamp, $nonce, $postData);
// echo $reply;

常见回调类型（示例）：

• Event: change_contact
  • ChangeType: create_user/update_user/delete_user/create_party/update_party/delete_party
• Event: change_external_contact
  • ChangeType: add_external_contact/edit_external_contact/del_external_contact/add_half_external_contact/del_half_external_contact
• Event: sys_approval_change
  • ChangeType: approve/reject/cancel

示例

参考 examples/basic.php、examples/callback.php、examples/customer_contact.php、examples/approval_oa.php、examples/miniprogram.php、examples/payment.php。