PHPackages                             tourze/wechat-official-account-fans-bundle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. tourze/wechat-official-account-fans-bundle

ActiveSymfony-bundle[API Development](/categories/api)

tourze/wechat-official-account-fans-bundle
==========================================

0.0.1(6mo ago)00MITPHPCI failing

Since Nov 11Pushed 4mo agoCompare

[ Source](https://github.com/tourze/wechat-official-account-fans-bundle)[ Packagist](https://packagist.org/packages/tourze/wechat-official-account-fans-bundle)[ RSS](/packages/tourze-wechat-official-account-fans-bundle/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (41)Versions (2)Used By (0)

WeChat Official Account Fans Bundle
===================================

[](#wechat-official-account-fans-bundle)

[English](README.md) | [中文](README.zh-CN.md)

📝 项目简介
------

[](#-项目简介)

本Bundle为微信公众号粉丝管理系统，完整对接微信公众号用户管理API，提供粉丝信息同步、标签管理、黑名单管理等功能。

### 🎯 核心功能

[](#-核心功能)

- **粉丝管理**：同步粉丝列表、用户信息、关注状态
- **标签管理**：创建、编辑、删除标签，批量打标签/取消标签
- **黑名单管理**：同步黑名单列表，批量拉黑/取消拉黑
- **自动同步**：定时任务自动同步数据，确保数据一致性

### 📊 数据模型

[](#-数据模型)

```
Account (公众号)
    ↓
Fan (粉丝) ←→ FanTag (关系) ←→ Tag (标签)

```

🚀 快速开始
------

[](#-快速开始)

### 安装依赖

[](#安装依赖)

```
composer require tourze/wechat-official-account-fans-bundle
```

### 注册Bundle

[](#注册bundle)

在 `config/bundles.php` 中添加：

```
return [
    // ...
    Tourze\WechatOfficialAccountFansBundle\WechatOfficialAccountFansBundle::class => ['all' => true],
];
```

🔧 API接口对应
---------

[](#-api接口对应)

### 标签管理API (8个)

[](#标签管理api-8个)

API名称Request类说明获取标签`GetTagsRequest`获取公众号已创建的标签创建标签`CreateTagRequest`创建标签编辑标签`UpdateTagRequest`编辑标签名删除标签`DeleteTagRequest`删除标签获取标签下粉丝`GetTagUsersRequest`获取标签下粉丝列表批量打标签`BatchTagUsersRequest`为用户批量打标签批量取消标签`BatchUntagUsersRequest`为用户批量取消标签获取用户标签`GetUserTagsRequest`获取用户身上的标签列表### 用户信息API (7个)

[](#用户信息api-7个)

API名称Request类说明获取用户信息`GetUserInfoRequest`获取用户基本信息批量获取用户信息`BatchGetUserInfoRequest`批量获取用户基本信息获取用户列表`GetFollowersListRequest`获取关注用户列表设置用户备注`SetUserRemarkRequest`设置用户备注名获取黑名单`GetBlacklistRequest`获取公众号黑名单列表拉黑用户`BatchBlacklistRequest`拉黑用户取消拉黑`BatchUnblacklistRequest`取消拉黑用户⚡ 同步策略
------

[](#-同步策略)

### 自动同步任务

[](#自动同步任务)

Command调度时间策略说明`SyncTagsCommand`02:05轻量全量同步标签列表`SyncFollowersCommand`02:10重量分页同步粉丝OpenID列表`SyncUserInfoCommand`02:30重量批量同步粉丝详细信息`SyncBlacklistCommand`02:50轻量全量同步黑名单列表### 手动执行

[](#手动执行)

```
# 同步标签
php bin/console wechat:official-account:sync-tags

# 同步粉丝列表
php bin/console wechat:official-account:sync-followers

# 同步用户详细信息
php bin/console wechat:official-account:sync-user-info

# 同步黑名单
php bin/console wechat:official-account:sync-blacklist
```

🏗️ 架构设计
-------

[](#️-架构设计)

### 核心实体

[](#核心实体)

Entity类中已包含完整的ORM注解，会自动生成对应的数据表：

```
// 粉丝实体
class Fan {
    private string $openid;        // 微信OpenID
    private ?string $unionid;      // UnionID
    private ?string $nickname;     // 昵称
    private FanStatus $status;     // 状态：已关注/已取消/已拉黑
    // ... 更多字段
}

// 标签实体
class Tag {
    private int $tagid;           // 微信标签ID
    private string $name;         // 标签名称
    private int $count;           // 粉丝数量
}

// 粉丝标签关系
class FanTag {
    private Fan $fan;
    private Tag $tag;
}
```

### 数据库表结构

[](#数据库表结构)

Entity会自动生成以下数据表：

- `wechat_official_account_fan` - 粉丝表
- `wechat_official_account_tag` - 标签表
- `wechat_official_account_fan_tag` - 粉丝标签关系表

📈 使用示例
------

[](#-使用示例)

### 获取粉丝列表

[](#获取粉丝列表)

```
$fanRepository = $this->get(FanRepository::class);
$fans = $fanRepository->findSubscribedByAccount($account);
```

### 查找标签下的粉丝

[](#查找标签下的粉丝)

```
$fans = $fanRepository->findByAccountAndTagId($account, $tagId);
```

### 获取用户的标签

[](#获取用户的标签)

```
$tags = $tagRepository->findByAccountAndFanOpenid($account, $openid);
```

🛡️ 安全特性
-------

[](#️-安全特性)

- **API频率限制**：内置延迟机制，避免触发微信API频次限制
- **批量处理**：遵循微信API限制，批量操作最多20个用户
- **错误隔离**：单个Account出错不影响其他Account同步
- **幂等性**：重复执行同步命令不会产生副作用

📋 系统要求
------

[](#-系统要求)

- PHP 8.1+
- Symfony 7.3+
- MySQL 8.0+
- 依赖 `tourze/wechat-official-account-bundle`

🔧 配置
----

[](#-配置)

### 日志配置

[](#日志配置)

在 `config/packages/monolog.yaml` 中添加：

```
monolog:
    channels: ['wechat_official_account_fans']
    handlers:
        wechat_fans:
            type: stream
            path: '%kernel.logs_dir%/wechat_fans.log'
            level: info
            channels: ['wechat_official_account_fans']
```

### 定时任务

[](#定时任务)

确保系统运行cron服务以执行自动同步任务。

⚠️ 注意事项
-------

[](#️-注意事项)

1. **微信API限制**：

    - 批量操作最多20个用户
    - 有调用频次限制
    - 需要access\_token认证
2. **数据同步**：

    - 首次同步可能需要较长时间
    - 用户昵称/头像受微信隐私政策限制
    - 取关用户信息可能无法获取
3. **性能优化**：

    - 大量粉丝时建议分批同步
    - 监控同步任务执行时间
    - 定期清理无效数据

🐛 故障排除
------

[](#-故障排除)

### 常见问题

[](#常见问题)

1. **同步失败**：检查access\_token是否有效
2. **部分数据缺失**：检查微信API权限设置
3. **性能问题**：调整批量处理大小

### 日志检查

[](#日志检查)

```
tail -f var/log/wechat_fans.log
```

📄 许可证
-----

[](#-许可证)

MIT License

🤝 贡献
----

[](#-贡献)

欢迎提交Issue和PR！

---

> 🎯 **设计原则**：简单实用，数据结构优先，消除特殊情况
>
> 💡 **架构思想**：基于Linus Torvalds的"好品味"工程理念设计

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance72

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity25

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

182d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e354fdb316da535dfa8ba2e9193a473c403b6bc6fb9170778d1dc50e304c6e9d?d=identicon)[tourze](/maintainers/tourze)

---

Top Contributors

[![tourze](https://avatars.githubusercontent.com/u/13899502?v=4)](https://github.com/tourze "tourze (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tourze-wechat-official-account-fans-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/tourze-wechat-official-account-fans-bundle/health.svg)](https://phpackages.com/packages/tourze-wechat-official-account-fans-bundle)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[contao/core-bundle

Contao Open Source CMS

1231.6M2.4k](/packages/contao-core-bundle)[ec-cube/ec-cube

EC-CUBE EC open platform.

78527.0k1](/packages/ec-cube-ec-cube)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[prestashop/prestashop

PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers.

9.0k15.4k](/packages/prestashop-prestashop)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)