EasyWeChat 3.x 用户管理指南：基于 openid 的用户信息获取、列表与备注更新

后端即时通讯【免费下载链接】easywechat 一个 PHP 微信 SDK项目地址https://gitcode.com/gh_mirrors/ea/easywechat点击查看免费下载用户信息的获取是微信公众平台开发中最常用的功能之一。本指南围绕 EasyWeChat 3.x 的$app-user用户服务系统讲解如何基于微信openid获取单个/批量用户信息、拉取关注者列表、修改用户备注以及查询用户所属用户组。读完本文你将掌握 EasyWeChat 3.x 用户管理 API 的完整调用方式、返回值结构并理解底层 SDK 对微信接口的封装机制可直接用于公众号后台的粉丝管理、用户画像等实战场景。前置约束以下所有用户信息的获取与更新都是基于微信的openid并且该用户必须是已关注当前账号的其它情况如未关注、粉丝已取关可能无法正常使用。获取用户服务实例与 EasyWeChat 其它服务一样用户管理服务通过主入口EasyWeChat\Foundation\Application类获取这也是 3.x 版本所有服务的统一入口服务端、用户、网页授权、菜单、素材等均由此分发。?php use EasyWeChat\Foundation\Application; // $options 为公众号配置数组app_id、secret、token、aes_key 等 $app new Application($options); $userService $app-user;获取到$userService之后即可调用下述全部用户管理 API。返回值Collection 集合对象EasyWeChat 3.x 的所有 API 返回值均为EasyWeChat\Support\Collection集合对象参见 3.x 教程汇总。该类实现了 PHP 预定义接口如ArrayAccess、Serializable等因此你可以用多种等价方式访问同一个字段$user $userService-get($openId); $user[nickname]; // 数组方式 $user-nickname; // 属性方式 $user-get(nickname); // get 方法此外还提供这些便捷操作检查属性是否存在$user-has(email)、统计元素个数$user-count()、转为数组$user-toArray()、生成 JSON$user-toJSON()等。这也是下文所有代码示例中既可以用-又可以用[]访问字段的原因。获取用户信息获取单个用户$user $userService-get($openId); echo $user-nickname; // 或 $user[nickname]get($openId)接收一个openid返回该用户的信息集合常用的字段包括nickname昵称、headimgurl头像、sex性别、country/province/city地域、subscribe是否关注、subscribe_time关注时间等。批量获取多个用户$users $userService-batchGet([$openId1, $openId2, ...]);batchGet($openIds)接收一个openid数组一次请求最多可查询 100 个用户适用于需要批量同步粉丝资料的场景例如配合用户列表分页拉取后逐批补齐详细信息。获取用户列表$users $userService-lists($nextOpenId null); // $nextOpenId 可选lists()用于分页拉取当前公众号的全部关注者openid注意只返回openid不含昵称头像等详情详情需再调用get或batchGet。$nextOpenId为上一次调用返回的游标用于翻页取下一批数据首次调用可省略。示例$users $userService-lists(); // result { total: 2, count: 2, data: { openid: [ , OPENID1, OPENID2 ] }, next_openid: NEXT_OPENID } $users-total; // 2返回结构字段说明字段含义total关注该公众账号的总粉丝数量count本次拉取到的粉丝openid数量单次上限 10000data.openid本次返回的openid数组next_openid拉取列表的最后一个openid作为下一页请求的$nextOpenId参数拉取完毕时为空字符串典型的分页全量拉取写法是while 循环 next_openid游标先lists()拿到第一页与next_openid将next_openid传给下一次lists($nextOpenId)直到返回的next_openid为空即表示全部关注者已拉取完毕。修改用户备注$userService-remark($openId, $remark); // 成功返回 boolean为指定openid的用户设置备注名常用于后台人工打标后的备注同步。备注名称长度限制为 30 个字符以内。示例$userService-remark($openId, 僵尸粉);调用成功后返回布尔值true失败时返回false。需要注意的是该接口本质上调用的是微信官方设置用户备注名接口只有已关注用户才能设置成功。获取用户所属用户组 ID$userService-group($openId);查询指定openid用户当前所属的用户组 ID老版公众号的用户分组体系返回值为数字类型的groupId。示例$userGroupId $userService-group($openId);拿到$userGroupId后可以进一步用于用户分组的移动、批量管理等操作。需要说明的是微信官方已将用户分组体系逐步演进为用户标签体系两者在 EasyWeChat 中分别对应独立的服务。用户标签与用户分组用户管理不仅仅只有信息查询还涉及精细化运营的两大工具用户标签基于标签对粉丝进行多维打标支持标签的增删改查、给用户打标签/取消标签、按标签拉取用户列表等是当前微信推荐的分层运营方式用户分组老版用户分组接口支持创建/删除/修改分组、移动用户到指定分组、批量移动等操作。更完整的用户管理能力例如黑名单拉黑/取消拉黑、openid 迁移转换等可参考新版文档 official-account/user新版 API 将其扩展为select批量获取、list列表、block/unblock拉黑/取消拉黑、blacklist黑名单、changeOpenid账号迁移 openid 转换等更丰富的方法。与网页授权的配合openid 从哪来上文所有接口都依赖openid而获取用户openid最常用的途径就是网页授权OAuth。在 EasyWeChat 3.x 中通过$app-oauth完成授权后返回的用户对象中$user-id即是微信的OPENID参见 3.x 网页授权文档$user $app-oauth-user(); $user-getId(); // 对应微信的 OPENID $user-getNickname(); // 对应微信的 nickname $user-getAvatar(); // 头像网址 $user-getOriginal(); // 原始 API 返回的全部信息注意当scope为snsapi_base时$oauth-user()对象里只有id即 openid没有昵称头像等其它信息需要完整资料时请使用snsapi_userinfo授权。拿到 openid 后即可配合本文的get/batchGet接口获取更详细的粉丝资料。底层机制SDK 如何调用微信接口虽然 3.x 的user服务在代码层面直接封装了微信cgi-bin/user/info、cgi-bin/user/info/batchget、cgi-bin/user/get、cgi-bin/user/info/updateremark等接口但理解当前仓库新版 EasyWeChat的底层封装逻辑有助于你推断 3.x 的实现原理与排错方向统一入口分发3.x 通过Application的魔术方法__get将$app-user分发到对应服务类新版仓库中这一设计演变为显式的服务容器参见 src/OfficialAccount/Application.php 中getServer、getAccessToken、getOAuth等服务初始化方法。HTTP 客户端与 Token 注入新版所有公众号 API 均走统一的AccessTokenAwareClientsrc/Kernel/HttpClient/AccessTokenAwareClient.php自动为请求附加access_token并以errcode非 0 作为失败判定src/OfficialAccount/Application.php同时基于https://api.weixin.qq.com/的base_urisrc/OfficialAccount/Application.php拼接用户管理各接口路径。3.x 的 user 服务在调用微信接口前同样会先经 access_token 中间件注入令牌token 过期时会自动刷新重试。AccessToken 的获取与刷新无论是 3.x 还是新版access_token 都通过app_idsecret换取并由缓存组件管理有效期避免每次请求都向微信换取新令牌相关实现可对照 src/OfficialAccount/AccessToken.php 与 src/Kernel/HttpClient/AccessTokenExpiredRetryStrategy.php。因此当你调用get、batchGet、lists、remark、group返回异常时排查顺序建议为先确认配置的app_id/secret是否正确、access_token 是否有效再确认目标openid是否真实关注了当前公众号未关注用户会返回错误码例如 40003 非法 openid。总结本指南完整覆盖了 EasyWeChat 3.x 用户管理的五类核心操作get($openId)/batchGet($openIds)单条/批量获取用户详细信息lists($nextOpenId null)分页拉取全部关注者 openid游标翻页remark($openId, $remark)修改用户备注group($openId)查询用户所属用户组 ID配合 用户标签、用户分组 完成精细化用户运营。所有返回值均为Collection集合既支持-属性访问也支持[]下标访问。只要保证 openid 正确且用户已关注即可在公众号后台稳定地获取与更新用户信息。赞分享后端即时通讯【免费下载链接】easywechat 一个 PHP 微信 SDK项目地址https://gitcode.com/gh_mirrors/ea/easywechat点击查看免费下载相关推荐3步掌握AI双语电子书制作bilingual_book_maker终极使用指南3步掌握AI双语电子书制作bilingual_book_maker终极使用指南 bilingual_book_maker是一款基于人工智能技术的多语言电子书制后端即时通讯WxJava小程序用户信息解密与OpenID获取实践指南WxJava小程序用户信息解密与OpenID获取实践指南 微信小程序用户信息解密机制解析 在微信小程序开发中获取用户信息是一个常见需求。传统方式通过wx.ge后端ToolJet 3.0.0-LTS 配置 Google 作为 OIDC 身份提供方从 Google Cloud 凭证生成到 Well-Known URL 的完整指南ToolJet 3.0.0 LTS 配置 Google 作为 OIDC 身份提供方从 Google Cloud 凭证生成到 Well Known URL 的完后端即时通讯上一篇Mojo 2023 年 8 月版本发布详解标准库重构、编译期内存求值与参数约定变更下一篇FastMCP 项目开发规范全解提交工作流、组件身份模型与发布流程实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考