Lark SDK for PHP

A lightweight, framework-agnostic PHP SDK for Lark OpenAPI.

Official OpenAPI style · Raw array parameters · Raw array responses · No token lifecycle management

English | 简体中文

A lightweight, framework-agnostic PHP SDK for Lark OpenAPI.

This project is under active development. The first milestone focuses on the SDK core, authentication APIs, Contacts, and IM modules.

Goals

• Provide a complete and maintainable PHP SDK for Lark OpenAPI.
• Keep the SDK close to the official OpenAPI design.
• Stay lightweight and avoid business-level abstractions.
• Work in plain PHP projects and common frameworks such as Laravel and Hyperf.
• Use PSR standards where possible.

Design Principles

• PHP >= 8.1.
• One Composer package.
• Framework-agnostic core.
• PSR-7, PSR-17, and PSR-18 based HTTP layer.
• Raw array request parameters.
• Raw array responses.
• No DTO requirement.
• No request parameter validation.
• No token lifecycle management.
• No business workflow orchestration.
• Webhook support will be added in a later milestone.

What This SDK Does

This SDK focuses on protocol-level OpenAPI capabilities:

• Build Lark OpenAPI requests.
• Send HTTP requests through PSR-compatible clients.
• Decode Lark API responses.
• Provide authentication API wrappers.
• Provide consistent exceptions.
• Support common request types such as JSON, query, form, multipart, upload, and download.

What This SDK Does Not Do

This SDK intentionally does not handle application business logic:

• It does not cache, refresh, or manage access tokens.
• It does not validate required fields or parameter types.
• It does not transform official field names.
• It does not provide business workflow helpers.
• It does not hide original Lark API error details.

Planned Architecture

src/
  Auth/
  Contracts/
  Core/
    Config.php
    Exception/
    Http/
    Response/
  OpenApi/
  Services/
  LarkClient.php
tests/
examples/
generator/

Planned Call Style

$client->auth()->tenantAccessToken()->create($payload);

$client->contact()->user()->get($query);

$client->im()->message()->create($payload);

Parameters are passed as arrays and responses are returned as arrays.

Roadmap

Milestone 1: Core

• Configuration model
• PSR-based HTTP layer
• Response decoder
• Exception model
• Authentication API wrappers

Milestone 2: High-Frequency APIs

• Contacts
• IM

Milestone 3: Collaboration APIs

• Drive
• Docs
• Calendar

Milestone 4: Additional Modules

• Approval
• Task
• Wiki
• Search
• Other OpenAPI modules

Milestone 5: Quality and Release

• Examples
• Tests
• CI
• Documentation
• Packagist release

Milestone 6: Webhook

• Signature verification
• Decryption
• Event parsing

Installation

The package is not published yet.

After the first release, it will be installable with Composer:

composer require lark-sdk-php/lark-sdk-php

Current Status

The current implementation includes:

• Core configuration
• PSR-based HTTP request pipeline
• Response decoding
• Unified exceptions
• Generated service/resource accessors for the existing OpenAPI request classes
• app_access_token and tenant_access_token API wrappers
• No token lifecycle management; callers provide and refresh access tokens themselves

Service calls now follow the planned SDK style, for example:

$client->contact()->user()->get(
    pathParams: ['user_id' => 'ou_xxx'],
    accessToken: 'tenant_access_token'
);

$client->im()->message()->create(
    query: ['receive_id_type' => 'open_id'],
    payload: [
        'receive_id' => 'ou_xxx',
        'msg_type' => 'text',
        'content' => '{"text":"hello"}',
    ],
    accessToken: 'tenant_access_token'
);

Quick Start

use Lark\Core\Config;
use Lark\LarkClient;
use GuzzleHttp\Client as GuzzleClient;
use Nyholm\Psr7\Factory\Psr17Factory;

$psr18Client = new GuzzleClient();
$factory = new Psr17Factory();

$client = new LarkClient(
    new Config(
        appId: 'your_app_id',
        appSecret: 'your_app_secret'
    ),
    $psr18Client,
    $factory,
    $factory
);

$token = $client->auth()->tenantAccessToken()->create();

$user = $client->contact()->user()->get(
    pathParams: ['user_id' => 'ou_xxx'],
    accessToken: $token['tenant_access_token']
);

See examples/get-tenant-access-token.php for a runnable example.

License

This project is open-sourced software licensed under the MIT license.