README

Lark Open 的 PHP SDK

Overtrue！尊重！

文档链接

• 飞书开放平台
• 飞书开放 API 列表

安装

$ composer require antcool/easy-lark -vvv

使用

创建实例

<?php

require 'vendor/autoload.php';

// 配置项
$config = [ 
    // 开启 debug 将在 logger_file 写入请求日志
    'debug' => true,
    // 指定日志文件
    'runtime_path' => '/tmp/easy-lark',

    // 应用信息
    'app_id' => '',
    'app_secret' => '',

    // curl 配置
    'http' => [
        'timeout' => 10,
        'base_uri' => 'https://open.feishu.cn',
    ],

    // 事件订阅信息
    'event' => [
        // Encrypt Key, 配置后将会自动解密消息
        'encrypt_key' => '',
        
        // Verification Token, 配置后将会自动校验消息 token 字段
        'verify_token' => '',
        
        // 是否开启请求来源签名验证(依赖 encrypt_key)
        'verify_request' => true,
    ],

    'access_token' => \AntCool\EasyLark\Support\AccessToken::class,
];

$app = new \AntCool\EasyLark\Application($config);

$client = $app->getClient();
$server = $app->getServer();
$config = $app->getConfig();

在 Laravel 中注册

$config = [
    'debug' => env('APP_DEBUG', false),
    'runtime_path' => storage_path('lark'),

    'app_id' => '',
    'app_secret' => '',

    'http' => [
        'timeout' => 10,
        'base_uri' => 'https://open.feishu.cn',
    ],
    
    'event' => [
        'encrypt_key' => '',
        'verify_token' => '',
        'verify_request' => true,
    ],
    
    'access_token' => \AntCool\EasyLark\Support\AccessToken::class,
]; 

// AppServiceProvider
public function boot()
{
    $this->app->singleton('lark', fn () => new Application($config));
}

$app = app('lark');

基本用法

try {
    // 发起 API 请求
    $response = $app->getClient()->getJson('uri', $query = []);
    $response = $app->getClient()->postJson('uri', $data = [], $query = []);
    
    // 免登授权
    $response = $app->getClient()->postJson('/open-apis/authen/v1/access_token', [
        'grant_type' => 'authorization_code',
        'code'       => 'dDieky8JXDywpnOlhR8ydf',
    ]);

   
    // 飞书审批 (飞书部分接口使用的 www.feishu.cn 域名, 但是 AccessToken 相同)
    $app->getClient()->postJson('https://www.feishu.cn/approval/openapi/v2/approval/get', [
        'approval_code' => '376DA07B-XXXX-XXXX-XXXX-98B7B907C6B3',
    ]);
    
    // 文件上传
    $file = new \AntCool\EasyLark\Support\File('file path');
    $app->getClient()->uploadFile(
        '/open-apis/im/v1/files' // 消息与群组消息文件上传,
        $file,
        ['file_type' => $file->extension, 'file_name' => $file->name]
    );
} catch (Throwable $exception) {
    echo $exception->getMessage();
}

事件订阅

需在应用后台订阅，审批事件订阅后需对 Approval Code 进行订阅

// 订阅指定审批单
$response = app('lark')->getClient()->postJson(
    'https://www.feishu.cn/approval/openapi/v2/subscription/subscribe',
    ['approval_code' => 'approval_code']
);

// 订阅事件处理
$server = $this->app->getServer();

// 方式一: 获取来自飞书服务器的推送事件内容, 你可以自行处理后 return $server->serve()
$event = $server->getRequestEvent();

// 方式二: 事件处理中间件处理, 可注册多个事件处理中间件
$server->with(function (Event $event, \Closure $next) {
    $body = $event->getBody(); // 推送的消息内容
    return $next($event);
});

// 方式三: 指定事件名称处理中间件
$server->addEventListener('approval_instance', function (Event $event, \Closure $next) {
    $body = $event->getBody(); // 推送的消息内容
    return $next($event);
});

// 别忘了调用 $server->serve();
return $server->serve();

自定义 AccessToken

class YourAccessToken implements AccessTokenInterface{
    public function getToken():string
    {
        
    }
}

$config = [
    'access_token' => YourAccessToken::class
];

TODO

• 事件订阅
• 消息模板
• 机器人

贡献

您可以通过以下三种方式之一进行贡献

1. 使用问题追踪器提交错误报告。
2. 在问题追踪器上回答问题或修复错误。
3. 贡献新功能或更新 wiki。

代码贡献过程并不十分正式。您只需确保遵循 PSR-0、PSR-1 和 PSR-2 编码规范。任何新的代码贡献都必须附有适用的单元测试。

许可证

MIT