# 微信用户服务

## 功能介绍

微信用户服务提供了获取用户信息、管理用户标签、获取关注者列表等功能，帮助开发者更好地管理和服务微信用户。

## 核心方法

### WechatUserService

#### getUserInfo(string $openId, string $lang = 'zh_CN')

获取用户信息。

**参数：**
- `$openId` - 用户的 OpenID
- `$lang` - 语言类型，默认为 'zh_CN'（简体中文），可选 'en'（英文）

**返回值：** 用户信息

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 获取用户信息
$userInfo = Wechat::officialAccount()->user->getUserInfo('o4HhH5tZ-xxxxx');
print_r($userInfo);

// 获取英文用户信息
$userInfoEn = Wechat::officialAccount()->user->getUserInfo('o4HhH5tZ-xxxxx', 'en');
print_r($userInfoEn);
```

#### getUsersInfo(array $openIds)

批量获取用户信息。

**参数：**
- `$openIds` - 用户的 OpenID 数组

**返回值：** 用户信息列表

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 批量获取用户信息
$openIds = ['o4HhH5tZ-xxxxx', 'o4HhH5tZ-yyyyy'];
$usersInfo = Wechat::officialAccount()->user->getUsersInfo($openIds);
print_r($usersInfo);
```

#### getFollowers(string $nextOpenId = '')

获取关注者列表。

**参数：**
- `$nextOpenId` - 第一个拉取的 OPENID，不填默认从头开始拉取

**返回值：** 关注者列表

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 获取关注者列表
$followers = Wechat::officialAccount()->user->getFollowers();
print_r($followers);

// 分页获取关注者列表
$nextOpenId = $followers['next_openid'];
$nextFollowers = Wechat::officialAccount()->user->getFollowers($nextOpenId);
print_r($nextFollowers);
```

#### createTag(string $name)

创建用户标签。

**参数：**
- `$name` - 标签名称，长度限制为 30 个字符

**返回值：** 创建结果

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 创建用户标签
$result = Wechat::officialAccount()->user->createTag('测试标签');
print_r($result);
```

#### getTags()

获取所有标签。

**返回值：** 标签列表

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 获取所有标签
$tags = Wechat::officialAccount()->user->getTags();
print_r($tags);
```

#### updateTag(int $tagId, string $name)

更新标签名称。

**参数：**
- `$tagId` - 标签 ID
- `$name` - 新的标签名称

**返回值：** 更新结果

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 更新标签名称
$result = Wechat::officialAccount()->user->updateTag(100, '新标签名称');
print_r($result);
```

#### deleteTag(int $tagId)

删除标签。

**参数：**
- `$tagId` - 标签 ID

**返回值：** 删除结果

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 删除标签
$result = Wechat::officialAccount()->user->deleteTag(100);
print_r($result);
```

#### tagUsers(array $openIds, int $tagId)

批量为用户打标签。

**参数：**
- `$openIds` - 用户的 OpenID 数组
- `$tagId` - 标签 ID

**返回值：** 操作结果

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 批量为用户打标签
$openIds = ['o4HhH5tZ-xxxxx', 'o4HhH5tZ-yyyyy'];
$result = Wechat::officialAccount()->user->tagUsers($openIds, 100);
print_r($result);
```

#### untagUsers(array $openIds, int $tagId)

批量为用户取消标签。

**参数：**
- `$openIds` - 用户的 OpenID 数组
- `$tagId` - 标签 ID

**返回值：** 操作结果

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 批量为用户取消标签
$openIds = ['o4HhH5tZ-xxxxx', 'o4HhH5tZ-yyyyy'];
$result = Wechat::officialAccount()->user->untagUsers($openIds, 100);
print_r($result);
```

#### getUserTags(string $openId)

获取用户身上的标签列表。

**参数：**
- `$openId` - 用户的 OpenID

**返回值：** 标签列表

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 获取用户身上的标签列表
$tags = Wechat::officialAccount()->user->getUserTags('o4HhH5tZ-xxxxx');
print_r($tags);
```

#### getTagUsers(int $tagId, string $nextOpenId = '')

获取标签下的用户列表。

**参数：**
- `$tagId` - 标签 ID
- `$nextOpenId` - 第一个拉取的 OPENID，不填默认从头开始拉取

**返回值：** 用户列表

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 获取标签下的用户列表
$users = Wechat::officialAccount()->user->getTagUsers(100);
print_r($users);

// 分页获取标签下的用户列表
$nextOpenId = $users['next_openid'];
$nextUsers = Wechat::officialAccount()->user->getTagUsers(100, $nextOpenId);
print_r($nextUsers);
```

#### setUserRemark(string $openId, string $remark)

设置用户备注名。

**参数：**
- `$openId` - 用户的 OpenID
- `$remark` - 备注名，长度限制为 30 个字符

**返回值：** 操作结果

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 设置用户备注名
$result = Wechat::officialAccount()->user->setUserRemark('o4HhH5tZ-xxxxx', '测试用户');
print_r($result);
```

## 用户信息结构

获取用户信息时，返回的数据结构如下：

```php
[
    'openid' => 'o4HhH5tZ-xxxxx',
    'nickname' => '张三',
    'sex' => 1, // 1 男，2 女，0 未知
    'language' => 'zh_CN',
    'city' => '广州',
    'province' => '广东',
    'country' => '中国',
    'headimgurl' => 'http://thirdwx.qlogo.cn/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkiaJSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/46',
    'privilege' => [],
    'unionid' => 'o6_bmasdasdsad6_2sgVt7hMZOPfL'
]
```

## 实际应用场景

### 1. 获取所有关注者信息

```php
use Kylin\Wechat\Facades\Wechat;

// 获取所有关注者信息
function getAllFollowers()
{
    $followers = [];
    $nextOpenId = '';
    
    do {
        $result = Wechat::officialAccount()->user->getFollowers($nextOpenId);
        if (isset($result['data']['openid'])) {
            $followers = array_merge($followers, $result['data']['openid']);
        }
        $nextOpenId = $result['next_openid'] ?? '';
    } while (!empty($nextOpenId));
    
    return $followers;
}

// 获取所有关注者的详细信息
function getAllFollowersInfo()
{
    $openIds = getAllFollowers();
    $usersInfo = [];
    
    // 每次最多获取 100 个用户信息
    $chunks = array_chunk($openIds, 100);
    foreach ($chunks as $chunk) {
        $result = Wechat::officialAccount()->user->getUsersInfo($chunk);
        if (isset($result['user_info_list'])) {
            $usersInfo = array_merge($usersInfo, $result['user_info_list']);
        }
    }
    
    return $usersInfo;
}

// 调用示例
$usersInfo = getAllFollowersInfo();
print_r($usersInfo);
```

### 2. 根据标签分组管理用户

```php
use Kylin\Wechat\Facades\Wechat;

// 根据用户行为打标签
function tagUserByBehavior($openId, $behavior)
{
    // 定义行为对应的标签 ID
    $behaviorTags = [
        'purchase' => 100, // 购买过商品
        'browse' => 101,   // 浏览过商品
        'share' => 102,     // 分享过内容
        'comment' => 103    // 评论过内容
    ];
    
    if (isset($behaviorTags[$behavior])) {
        $tagId = $behaviorTags[$behavior];
        Wechat::officialAccount()->user->tagUsers([$openId], $tagId);
    }
}

// 调用示例
tagUserByBehavior('o4HhH5tZ-xxxxx', 'purchase');

// 根据标签发送不同的消息
function sendMessageByTag($tagId, $message)
{
    // 获取标签下的所有用户
    $openIds = [];
    $nextOpenId = '';
    
    do {
        $result = Wechat::officialAccount()->user->getTagUsers($tagId, $nextOpenId);
        if (isset($result['data']['openid'])) {
            $openIds = array_merge($openIds, $result['data']['openid']);
        }
        $nextOpenId = $result['next_openid'] ?? '';
    } while (!empty($nextOpenId));
    
    // 向这些用户发送消息
    foreach ($openIds as $openId) {
        Wechat::officialAccount()->message->sendTextMessage($openId, $message);
    }
}

// 调用示例
sendMessageByTag(100, '亲爱的会员，我们为您准备了专属优惠！');
```
