📖 背景故事

最近在工作中需要将我们的系统与飞书进行深度集成，包括消息推送、群组管理、用户信息获取等功能。虽然飞书官方提供了完整的 API 文档，但在实际开发中发现：

1. 重复造轮子：每次调用 API 都要处理 token 获取、刷新、错误处理等
2. 类型不安全：PHP 的弱类型特性让 API 调用容易出错
3. 集成复杂：Laravel 项目中的集成体验不够友好

于是，我决定开发一个简单易用、类型安全、Laravel 友好的飞书 SDK！

✨ 核心特性

🎯 简洁的 API 设计

// 发送消息就是这么简单！
$message = new Message('app_id',  'app_secret');
$message->send('user_id',  'text',  'Hello, World!');

// 群组操作也很直观
$group = new Group('app_id',  'app_secret');
$chatId = $group->search('技术交流群');
$message->send($chatId,  'text',  '群组消息测试');

🛡️ 类型安全（PHP 8.1+ 枚举）

use Yuxin\Feishu\Enums\MessageTypeEnum;
use Yuxin\Feishu\Enums\ReceiveIDTypeEnum;

// 使用枚举确保类型安全
$message->send(
    'user_id',
    MessageTypeEnum::Text->value,  // 只能是预定义的消息类型
    '消息内容',
    'open_id',  // 用户ID类型
    ReceiveIDTypeEnum::OpenID->value // 接收者ID类型
);

🚀 完整的消息类型支持

• 📝 文本消息
• 🖼️ 图片消息
• 📁 文件消息
• 📰 富文本消息
• 🎵 音频消息
• 🎬 视频消息
• 😀 表情消息
• 🎴 交互式卡片
• 🔗 群组/用户分享

🏗️ Laravel 深度集成

// 在 .env 中配置
FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret

// 服务容器中直接使用
app('feishu.message')->send('user_id',  'text',  'Hello!');
app('feishu.group')->search('群组名称');

🏗️ 项目架构

src/
├── AccessToken.php # 智能 Token 管理（自动获取/刷新）
├── Message.php # 消息发送核心
├── Group.php # 群组管理
├── User.php # 用户管理
├── ServiceProvider.php # Laravel 服务提供者
├── Contracts/ # 接口定义（可扩展）
├── Enums/ # 类型安全枚举
└── Exceptions/ # 异常处理

🔧 技术亮点

1. 智能 Token 管理

• 自动获取和刷新访问令牌
• 内置缓存机制，避免重复请求
• 异常处理和重试机制

2. 类型安全设计

• 使用 PHP 8.1+ 枚举类型
• 严格的参数验证
• 完整的 PHPDoc 文档

3. 开发者友好

• 详细的错误提示
• 完整的测试覆盖（Pest）
• 代码质量检查（PHPStan + Laravel Pint）

4. 生产就绪

• 异常处理机制
• HTTP 客户端配置
• 灵活的依赖注入

📱 实际应用场景

1. 企业通知系统

// 系统异常告警
$message->send('admin_user_id', 'text', '⚠️ 系统检测到异常，请及时处理！');

// 定时任务通知
$message->send('tech_group_id', 'text', '✅ 数据同步任务已完成');

2. 工作流集成

// 审批流程通知
$message->send($approverId, 'interactive', json_encode([
    'type' => 'card',
    'content' => [
        'title' => '新的审批请求',
        'elements' => [
            ['type' => 'button', 'text' => '查看详情', 'url' => $approvalUrl]
        ]
    ]
]));

3. 数据报表推送

// 每日数据汇总
$message->send('management_group_id', 'post', json_encode([
    'title' => '📊 今日数据汇总',
    'content' => [
        ['type' => 'text',  'text' => "新增用户：{$newUsers} 人"],
        ['type' => 'text',  'text' => "活跃用户：{$activeUsers} 人"]
    ]
]));

🚀 快速开始

安装

composer  require  zhaiyuxin/feishu

基础使用

use Yuxin\Feishu\Message;

$message =  new  Message('your_app_id', 'your_app_secret');

// 发送文本消息
$message->send('user_open_id', 'text', 'Hello from SDK!');

// 发送富文本消息
$message->send('group_chat_id', 'post', json_encode([
    'title'  =>  '重要通知',
    'content'  =>  [
        ['type' => 'text',  'text' => '这是一条重要通知']
    ]
]));

Laravel 集成

// 发布配置
php artisan vendor:publish --provider="Yuxin\Feishu\ServiceProvider"

// 在控制器中使用
class  NotificationController  extends  Controller
{
    public  function  sendNotification(Request  $request)
    {
        $message = app('feishu.message');
        $message->send($request->user_id, 'text', $request->content);

        return  response()->json(['message' => '发送成功']);
    }
}

🧪 测试与质量

项目采用现代化的开发工具链：

• Pest - 优雅的测试框架
• PHPStan - 静态代码分析
• Laravel Pint - 代码风格检查
• GitHub Actions - 自动化测试和部署

运行测试

composer  test

代码质量检查

composer  lint

🌟 为什么选择这个 SDK？

1. 学习成本低：API 设计直观，5 分钟即可上手
2. 类型安全：PHP 8.1+ 枚举确保编译时错误检查
3. 生产就绪：完整的异常处理和错误恢复机制
4. Laravel 友好：开箱即用的服务提供者
5. 持续维护：活跃的开发和社区支持

🚀 未来规划

• 支持更多消息类型（如小程序卡片）
• 添加消息撤回和编辑功能
• 支持批量消息发送
• 增加更多群组管理功能
• 提供更多 Laravel 集成特性

🤝 参与贡献

欢迎提交 Issue 和 Pull Request！项目采用 MIT 许可证，可以自由使用和修改。

📚 相关链接

• GitHub: zhaiyuxin103/feishu
• Packagist: zhaiyuxin/feishu
• 文档: 在线文档

如果你也在做飞书集成，或者对 PHP 开源项目感兴趣，欢迎试用这个 SDK！有任何问题或建议，都可以在 GitHub 上讨论。

希望这个工具能帮助到更多开发者，让企业集成变得更简单！ 🚀

本作品采用《CC 协议》，转载必须注明作者和本文链接