php微信框架|专业微信生态开发引擎

为PHP开发者打造的高可用、高扩展微信全平台开发解决方案,覆盖公众号、小程序、企业微信、微信开放平台,提供完整API封装、安全机制、消息中间件、OAuth2授权、支付接入、素材管理、模板推送等标准化能力,助您3天上线微信应用系统。

核心功能特性

⚡

全平台适配

统一接口封装公众号、小程序、企业微信、微信开放平台,支持多账号配置管理,一套代码跨平台运行。

⚙️

高安全性保障

内置消息加解密(AES/CBC/PKCS7)、签名验证、Token校验、IP白名单过滤、敏感词过滤机制,严格遵循微信安全规范。

🛡️

消息中间件

支持异步消息队列处理(Redis/MySQL),实现消息重试、失败归档、延迟推送、模板消息批量发送、客服消息定时触发。

🌐

OAuth2授权体系

完整实现网页授权(snsapi_base/snsapi_userinfo)、静默授权与弹窗授权双流程,支持用户信息缓存与 unionID 统一身份识别。

💳

微信支付集成

深度集成Native、JSAPI、小程序支付、企业付款,支持分账、退款、账单下载、支付回调验证与幂等处理。

📊

数据统计分析

对接用户分析、消息分析、接口分析、网页分析接口,支持数据聚合、趋势图表生成与报表导出。

模块化技术架构

消息处理引擎

完整支持微信服务器消息推送与客服消息主动发送机制,提供消息类型识别、内容解析、状态回执、防重放攻击、消息加密解密、消息去重等核心能力。

支持消息类型:

  • 文本消息(text)
  • 图片消息(image)
  • 语音消息(voice)
  • 视频消息(video)
  • 小视频消息(shortvideo)
  • 地理位置消息(location)
  • 链接消息(link)
  • 事件推送(event):关注/取消关注、扫描二维码、点击菜单、地理位置上报、支付成功通知等
  • 小程序消息卡片(miniprogrampage)

典型处理流程:

  1. 微信服务器推送消息 → 携带 signature、timestamp、nonce、encrypt_type
  2. 服务端校验 signature(SHA1(token+timestamp+nonce))
  3. 若 encrypt_type=aes,则使用 AESKey 解密消息体
  4. 解析 XML / JSON,提取消息类型与内容
  5. 业务逻辑处理(如:关键词回复、订单查询、用户咨询转人工)
  6. 构造响应消息(文本/图文/菜单/小程序卡片),加密后返回

示例代码:

消息类型响应策略
关键词:优惠券图文消息 + 活动链接 + 二维码
地理位置上报附近门店列表(含距离排序)
支付成功事件发送订单详情 + 发票申请入口
菜单点击:customer_service跳转客服聊天窗口或返回“转人工”提示

用户管理与身份体系

基于微信 UnionID 机制,实现跨应用用户身份统一识别。支持用户信息缓存、标签管理、黑名单处理、粉丝分组、用户行为追踪等。

核心能力:

  • 通过 OAuth2 授权获取用户 openid(单公众号)或 unionid(同一主体下多应用)
  • 用户信息同步至本地数据库(昵称、头像、性别、地区、关注时间、标签)
  • 标签批量绑定/解绑(单次最多50个用户)
  • 黑名单管理(拉黑/取消拉黑,需用户主动操作)
  • 用户分组迁移(旧分组ID映射至新分组)

UnionID 生成规则:

当用户在同一微信开放平台账号下的多个应用(公众号、小程序、移动应用)中授权登录后,微信将为该用户生成唯一 UnionID。若未绑定开放平台,则各应用返回独立 openid。

典型业务场景:

  • 用户在公众号关注后,在小程序登录时自动识别为同一人
  • 用户从APP跳转至公众号菜单页,无需重复授权
  • 统一会员体系:订单、积分、等级跨平台同步

素材管理与内容运营

覆盖临时素材(3天有效期)与永久素材(图文、图片、语音、视频、封面)的上传、查询、删除、修改能力,支持图文消息批量管理与封面图预览。

永久素材类型:

  • 图文消息(news):单条最多8张图文,支持封面+标题+摘要+原文链接
  • 图片(image):上传后生成 media_id,用于消息发送或菜单
  • 语音(voice):需符合微信格式(MP3/WMA/WAV/AMR),时长≤60秒
  • 视频(video):需上传 description 字段(标题/简介)

图文素材管理最佳实践:

  1. 上传封面图 → 获取 media_id
  2. 构造图文消息 JSON:title、thumb_media_id、author、digest、show_cover、content、content_source_url
  3. 调用“新增永久图文素材”接口
  4. 返回 media_id,用于后续群发或菜单跳转

封面图规范:

  • 尺寸建议:900×500像素
  • 格式:JPG/PNG
  • 大小:≤64KB
  • 禁止含二维码、水印、第三方LOGO

微信支付集成

支持Native(扫码支付)、JSAPI(公众号支付)、小程序支付、H5支付、企业付款等全场景接入,严格遵循微信支付V3 API规范。

JSAPI支付流程:

  1. 用户点击“立即支付” → 调用统一下单接口(trade_type=JSAPI)
  2. 获取 prepay_id → 构造支付参数(appId、timeStamp、nonceStr、package、signType、paySign)
  3. 前端调用 WeixinJSBridge.invoke('getBrandWCPayRequest', ...)
  4. 用户输入密码 → 支付成功 → 微信服务器异步通知(POST /pay/notify)
  5. 服务端校验签名 → 更新订单状态 → 返回 SUCCESS

支付回调验签要点:

  • 检查 request_id 是否重复(防重放)
  • 验证签名(使用微信支付平台证书)
  • 确认 out_trade_no 与本地订单匹配
  • 校验 total_fee 是否一致
  • 更新订单状态后,必须返回 <xml><return_code><![CDATA[SUCCESS]]></return_code></xml>

常见支付失败原因:

错误码说明解决方案
INVALID_REQUEST参数格式错误或缺失检查 spbill_create_ip、notify_url 是否符合规范
ORDER_PAID订单已支付禁止重复下单,需返回“订单已存在”提示
NOTENOUGH余额不足提示用户更换支付方式(如券/红包)
AUTH_NO_AUTH无支付权限检查商户号是否开通对应产品(如小程序支付需绑定小程序)

自定义菜单配置

支持一级菜单(最多3个)与二级菜单(每项最多5个),支持点击(click)、扫码(scancode_push)、跳转(view)、小程序(miniprogram)等11种事件类型。

菜单创建JSON结构示例:

{
  "button": [
    {
      "type": "click",
      "name": "今日歌曲",
      "key": "V1001_TODAY_MUSIC"
    },
    {
      "name": "菜单",
      "sub_button": [
        {
          "type": "view",
          "name": "搜索",
          "url": "https://www.soso.com/"
        },
        {
          "type": "miniprogram",
          "name": "小程序",
          "appid": "wx286b93c14bb693aa",
          "pagepath": "pages/index/index",
          "icon_url": "http://mmbiz.qpic.cn/mmbiz_png/0?wx_fmt=png"
        }
      ]
    }
  ]
}

菜单事件响应:

  • 点击菜单事件推送:event=CLICK,eventKey=V1001_TODAY_MUSIC
  • 扫描二维码事件:event=SCAN,eventKey=QR_SCENE_123123
  • 跳转小程序事件:event=VIEW_MINIPROGRAM,eventKey=xxx

菜单推送消息规则:

  1. 用户点击菜单 → 微信服务器推送事件消息
  2. 开发者服务器处理事件 → 返回文本/图文/菜单等响应
  3. 若未响应,用户将看到“该公众号暂时无法提供服务”提示

版本演进与里程碑

2023.12 • v3.2.0
微信支付V3协议全面升级

完成微信支付V3 API(RFC7515签名)重构,新增商户券、商家券、分账、支付即服务(Payment as a Service)支持,适配微信支付商户平台V3接口规范。

2023.08 • v3.1.5
企业微信集成增强

新增企业微信会话存档API封装、客户联系(contact)能力支持(添加外部联系人、标签管理、客户详情查询),满足企业级办公协同需求。

2023.03 • v3.0.0
跨平台架构重构

采用模块化设计,解耦公众号、小程序、开放平台核心逻辑;引入PSR-18 HTTP客户端抽象层,兼容Guzzle/Swoole/ReactPHP;支持Laravel 9/10、ThinkPHP 6.0+无缝集成。

2022.11 • v2.8.2
小程序订阅消息支持

新增订阅消息模板管理(subscribe.getTemplateList)、订阅交互(subscribe.requestTemplateId)、消息发送(message.subscribe.send),适配小程序消息触达新机制。

2022.06 • v2.7.0
微信开放平台账号绑定

实现移动应用/公众号/小程序三端账号绑定,支持unionid自动拉取、绑定关系查询、解绑操作,解决多应用用户身份割裂问题。

2021.12 • v2.5.1
JS-SDK 1.6.0适配

全面支持微信JS-SDK 1.6.0新特性:视频播放器、地理位置接口增强、摇一摇周边、设备信息获取,修复iOS 15 Safari兼容性问题。

2021.03 • v2.0.0
首次开源发布

开源php微信框架 2.0.0,提供Composer包管理、完整文档、Docker部署方案,累计Star数突破8,200+。

典型应用场景与案例

连锁餐饮品牌:会员订阅号

基于php微信框架构建会员中心,集成:

  • 扫码点餐(JSAPI支付)
  • 会员卡领取(OAuth2授权)
  • 积分兑换(模板消息推送)
  • 门店地图(地理位置上报)

实现用户转化率提升37%,复购频次提高1.8倍。

在线教育平台:知识付费小程序

开发微信小程序+公众号双端系统:

  • 小程序:课程购买(小程序支付)
  • 公众号:学习提醒(订阅消息)、资料下载(素材管理)
  • 后台:用户学习路径追踪、完课率统计

月活用户达24万,付费转化率12.6%。

物流科技公司:企业微信协同平台

构建企业微信客户联系系统:

  • 自动分配客户(标签+地域匹配)
  • 聊天记录存档(企业微信API)
  • 客户标签自动打标(行为分析)
  • 服务满意度调研(模板消息)

客服响应时效提升至23秒,客户留存率提高28%。

常见问题解答

Q1:为什么公众号关注后无法收到自动回复?

A:请依次检查:

  • 微信服务器配置中的Token、EncodingAESKey是否与代码一致
  • 消息加解密模式是否与服务器配置匹配(兼容模式/安全模式)
  • 开发者服务器是否正常响应(查看日志,确认无5xx错误)
  • 是否在公众平台后台设置了自动回复规则(规则优先级高于代码)
Q2:OAuth2授权后获取不到用户头像?

A:需确认:

  • 授权范围是否为 snsapi_userinfo(非 snsapi_base)
  • 用户是否已关注公众号(未关注则仅返回openid)
  • access_token 是否有效(检查 expires_in)
  • 用户昵称是否含特殊字符(如emoji),需在数据库字段使用 utf8mb4 编码
Q3:JS-SDK调用“chooseImage”失败?

A:常见原因:

  • 未在公众号后台配置JS接口安全域名(设置 → 公众号设置 → 功能设置)
  • 签名生成使用了错误的URL(必须是当前页面完整URL,不含#哈希)
  • jsapi_ticket 是否过期(有效期7200秒,需缓存)
  • AppID 是否与当前公众号一致
Q4:支付回调未触发?

A:请排查:

  • 回调URL是否能公网访问(微信服务器需直接访问,不可跳转)
  • 是否正确解析POST数据(需使用 file_get_contents('php://input'))
  • 是否返回正确格式的XML(必须为 <xml> 根节点,非 <response>)
  • 微信服务器通知重试机制:失败后15秒/30秒/3分钟/5分钟/10分钟/30分钟/1小时/2小时/3小时重试,共8次
Q5:如何实现用户分组迁移?

A:操作步骤:

  1. 查询分组ID:GET https://api.weixin.qq.com/cgi-bin/groups/get?access_token=ACCESS_TOKEN
  2. 查询某分组用户列表:GET https://api.weixin.qq.com/cgi-bin/user/get?access_token=ACCESS_TOKEN&next_openid=NEXT_OPENID
  3. 批量移动用户:POST https://api.weixin.qq.com/cgi-bin/groups/members/batchtagging?access_token=ACCESS_TOKEN
  4. 删除空分组(可选):POST https://api.weixin.qq.com/cgi-bin/groups/update?access_token=ACCESS_TOKEN