# line/line-bot-sdk-php architecture

> Architecture diagram of the GitHub repository line/line-bot-sdk-php, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/line/line-bot-sdk-php
- Repository: https://github.com/line/line-bot-sdk-php

## Overview

##### Project type and purpose
- This is a client-SDK library (LINE Messaging API SDK for PHP), generated from an OpenAPI spec, to simplify building LINE bots.
- It provides:
- HTTP clients (Guzzle) wrapped in domain-specific APIs (MessagingApi, InsightApi, LiffApi, etc.)
- Domain models, serializers, exceptions
- A request parser for incoming webhooks
- Laravel integration (facades + service provider)
- Examples demonstrating a webhook server (EchoBot, KitchenSink)

##### High-level file structure
- src/clients/**…** – generated API clients per domain
- src/constants/**…** – constant definitions for enums, header names
- src/parser/**…** – webhook request parsing
- src/webhook/**…** – models for incoming webhook events + dummy API
- src/laravel/**…** – Laravel facades & config + tests
- examples/**…** – two sample bot applications showing practical usage
- docs/**…**, tools/**…** – documentation, generator templates, build scripts, CI configs

##### Core architectural components
A. External Systems
- LINE Platform (Messaging API endpoints, Webhook calls)
- Composer/Packagist (distribution)
- Guzzle HTTP client (PSR-18)
- (Optional) Laravel application environment

B. SDK Core
1. Domain API Clients
– MessagingApiApi, InsightApi, LiffApi, ManageAudienceApi, ChannelAccessTokenApi
– Each: Configuration → HTTP client → API calls → Models & ObjectSerializer → ApiException
2. Constants
– ActionType, MessageType, HTTPHeader, Flex component enums
3. Serializer & Model Layer
– ObjectSerializer marshals/unmarshals JSON ↔ PHP models
4. Parser
– EventRequestParser + SignatureValidator for incoming webhooks
– ParsedEvents returned to user code
5. Webhook Models
– Typed event payloads for incoming data (FollowEvent, MessageEvent, etc.)
6. Laravel Integration
– LINEBotServiceProvider registers facades
– Facades (LINEMessagingApi, LINEInsightApi, etc.) wrap respective client APIs

C. Sample Applications (Examples)
– EchoBot: minimal route, handles text messages
– KitchenSink: full-stack example with routing, event handlers, static assets

##### Interactions and data flows
- Outbound: SDK Core → Guzzle HTTP → LINE Messaging API endpoints → JSON response → SDK Model
- Inbound Webhook: LINE Platform → Your HTTP endpoint → Parser (SignatureValidator → EventRequestParser) → ParsedEvents → User handler code
- Laravel app: User code uses Facades → underlying SDK client → HTTP → LINE
- Examples: glue code (Route.php, EventHandler) wires parser + SDK to business logic

##### Architectural patterns & principles
- Layered architecture:
- Presentation (examples / user code)
- SDK façade (Domain APIs, Parser)
- Transport (Guzzle HTTP)
- Models & serialization
- Code generation from OpenAPI: consistent structure across clients
- Facade pattern for Laravel integration
- Dependency inversion: your code depends on abstractions (ClientInterface, Api classes)
- Builder/setter pattern for request objects

- Major modules (Clients, Parser, Models, Constants, Laravel)
- Protocols (HTTP, JSON) and key classes
- Keep it detailed—don’t collapse distinct API clients or model layers
- Validate with README sections (Getting started, Components) to ensure no missing pieces

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Systems"
        LINE["LINE Platform"]:::external
        Composer["Composer/Packagist"]:::external
        Guzzle["Guzzle HTTP Client"]:::external
    end

    subgraph "SDK Core"
        subgraph "Domain API Clients"
            CAT["ChannelAccessTokenApi"]:::sdk
            INS["InsightApi"]:::sdk
            LIFF["LiffApi"]:::sdk
            MAU["ManageAudienceApi"]:::sdk
            MSG["MessagingApiApi & MessagingApiBlobApi"]:::sdk
        end
        subgraph "Constants"
            ACT["ActionType"]:::sdk
            MSGT["MessageType"]:::sdk
            HHTTP["HTTPHeader"]:::sdk
            FLEX["Flex Components"]:::sdk
        end
        subgraph "Models & Serialization"
            OBJSER["ObjectSerializer"]:::sdk
            MODELS["Models"]:::sdk
            APIEX["ApiException"]:::sdk
        end
        subgraph "Parser"
            SIG["SignatureValidator"]:::sdk
            PRS["EventRequestParser"]:::sdk
            PEV["ParsedEvents"]:::sdk
        end
        subgraph "Webhook Models"
            WMODELS["Webhook Models"]:::sdk
            WDUMMY["DummyApi"]:::sdk
        end
    end

    subgraph "Laravel Integration"
        SBP["LINEBotServiceProvider"]:::laravel
        FAC["Facades"]:::laravel
        CONF["line-bot.php"]:::laravel
    end

    subgraph "Application Code (Examples)"
        ECHO["EchoBot"]:::app
        KITCHEN["KitchenSink"]:::app
    end

    %% Relationships
    ECHO -->|"uses"| MSG
    KITCHEN -->|"uses"| MSG
    FAC -->|"calls"| MSG
    CAT -->|"HTTP CALL"| Guzzle
    INS -->|"HTTP CALL"| Guzzle
    LIFF -->|"HTTP CALL"| Guzzle
    MAU -->|"HTTP CALL"| Guzzle
    MSG -->|"HTTP CALL"| Guzzle
    Guzzle -->|"HTTP POST/JSON"| LINE
    LINE -->|"Webhook"| PRS
    PRS -->|"parseEventRequest()"| ECHO
    PRS -->|"parseEventRequest()"| KITCHEN

    %% Click Events
    click CAT "https://github.com/line/line-bot-sdk-php/blob/master/src/clients/channel-access-token/lib/Api/ChannelAccessTokenApi.php"
    click INS "https://github.com/line/line-bot-sdk-php/blob/master/src/clients/insight/lib/Api/InsightApi.php"
    click LIFF "https://github.com/line/line-bot-sdk-php/blob/master/src/clients/liff/lib/Api/LiffApi.php"
    click MAU "https://github.com/line/line-bot-sdk-php/blob/master/src/clients/manage-audience/lib/Api/ManageAudienceApi.php"
    click MSG "https://github.com/line/line-bot-sdk-php/blob/master/src/clients/messaging-api/lib/Api/MessagingApiApi.php"
    click OBJSER "https://github.com/line/line-bot-sdk-php/blob/master/src/clients/messaging-api/lib/ObjectSerializer.php"
    click ACT "https://github.com/line/line-bot-sdk-php/blob/master/src/constants/ActionType.php"
    click MSGT "https://github.com/line/line-bot-sdk-php/blob/master/src/constants/MessageType.php"
    click HHTTP "https://github.com/line/line-bot-sdk-php/blob/master/src/constants/HTTPHeader.php"
    click FLEX "https://github.com/line/line-bot-sdk-php/tree/master/src/constants/Flex/"
    click PRS "https://github.com/line/line-bot-sdk-php/blob/master/src/parser/lib/EventRequestParser.php"
    click SIG "https://github.com/line/line-bot-sdk-php/blob/master/src/parser/lib/SignatureValidator.php"
    click PEV "https://github.com/line/line-bot-sdk-php/blob/master/src/parser/lib/ParsedEvents.php"
    click WMODELS "https://github.com/line/line-bot-sdk-php/tree/master/src/webhook/lib/Model/"
    click WDUMMY "https://github.com/line/line-bot-sdk-php/blob/master/src/webhook/lib/Api/DummyApi.php"
    click SBP "https://github.com/line/line-bot-sdk-php/blob/master/src/laravel/lib/LINEBotServiceProvider.php"
    click FAC "https://github.com/line/line-bot-sdk-php/tree/master/src/laravel/lib/Facades/"
    click CONF "https://github.com/line/line-bot-sdk-php/blob/master/src/laravel/lib/config/line-bot.php"
    click ECHO "https://github.com/line/line-bot-sdk-php/blob/master/examples/EchoBot/src/LINEBot/EchoBot/Route.php"
    click KITCHEN "https://github.com/line/line-bot-sdk-php/blob/master/examples/KitchenSink/src/LINEBot/KitchenSink/Route.php"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef sdk fill:#90EE90,stroke:#333,stroke-width:1px
    classDef laravel fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef app fill:#FFA500,stroke:#333,stroke-width:1px
```
