Skip to content
This repository was archived by the owner on Oct 25, 2026. It is now read-only.

Latest commit

 

History

History
118 lines (101 loc) · 2.97 KB

architecture.md

File metadata and controls

118 lines (101 loc) · 2.97 KB

php-mysql-cli - Architecture

Last updated: 2026-10-25

Back to README

Overview

graph TB
    A[Caller] --> B[SQL::table]
    A --> R[SQL::read / write]
    ENV[DB_READ_* / DB_WRITE_*] --> C[initConnection]
    B --> C
    R --> C
    B --> D[Static builder state]
    D --> E[get / update / insert SQL assembly]
    E --> Q[query]
    R --> Q
    C --> P[Static PDO connection]
    P --> Q
    Q --> M[(MySQL)]
    Q --> L[error_log slow query / error]
Loading

Module: Connection

initConnection() reads the target's environment variables and opens a PDO connection when none exists, retrying with exponential backoff on failure.

graph TB
    subgraph Connection
        IN[initConnection target] --> HAS{client exists?}
        HAS -->|Yes| RET[Return]
        HAS -->|No| ENVR[Read DB_target_*]
        ENVR --> DSN[Build mysql DSN]
        DSN --> TRY[new PDO]
        TRY -->|OK| TO[SET wait_timeout / interactive_timeout 600]
        TRY -->|Fail and under 3 tries| SLEEP[usleep 100ms x 2^n]
        SLEEP --> TRY
        TRY -->|3rd failure| THROW[Throw PDOException]
    end
Loading

Module: Query Builder

The builder keeps conditions in static properties and clears them with resetState() after each execution.

graph TB
    subgraph QueryBuilder
        T[table] --> S[selects]
        T --> J[joins]
        T --> W[wheres + bindings]
        T --> G[groups]
        T --> O[orders]
        T --> LO[limit / offset]
        T --> TT[withTotal]
        S --> GET[get]
        J --> GET
        W --> GET
        G --> GET
        TT -->|wrap in COUNT OVER subquery| GET
        O --> GET
        LO --> GET
        W --> UPD[update]
        FN[SQL function allowlist] --> UPD
        INS[insert / insertGetId]
        GET --> RS[resetState]
        UPD --> RS
        INS --> RS
    end
Loading

Module: Executor

query() handles prepare, typed binding, timing, and result shaping.

graph TB
    subgraph Executor
        QI[query sql params] --> CK{client exists?}
        CK -->|No| ERR0[Throw Exception]
        CK -->|Yes| PR[prepare]
        PR --> BD[bindValue INT / BOOL / NULL / STR]
        BD --> EX[execute with timing]
        EX -->|over 20ms| SL[error_log Slow Query]
        EX --> TY{Starts with UPDATE / INSERT?}
        TY -->|Yes| META[info / insert_id / affected_rows]
        TY -->|No| ROWS[fetchAll ASSOC]
        EX -->|PDOException| EL[error_log and rethrow]
    end
Loading

Data Flow

sequenceDiagram
    participant Caller
    participant SQL
    participant PDO
    participant MySQL
    Caller->>SQL: table("users")
    SQL->>PDO: initConnection("READ") (first call only)
    Caller->>SQL: where / orderBy / limit
    Caller->>SQL: get()
    SQL->>SQL: assemble SELECT
    SQL->>PDO: prepare + bindValue
    PDO->>MySQL: execute
    MySQL-->>PDO: rows
    PDO-->>SQL: fetchAll
    SQL->>SQL: resetState()
    SQL-->>Caller: array
Loading

©️ 2024 邱敬幃 Pardn Chiu