# iamludal/mysql-querybuilder architecture

> Architecture diagram of the GitHub repository iamludal/mysql-querybuilder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iamludal/mysql-querybuilder
- Repository: https://github.com/iamludal/mysql-querybuilder

## Overview

##### Project Type and Purpose
- This is an open‑source PHP library (packaged via Composer) that implements a fluent query‑builder DSL for MySQL (and potentially other PDO‑compatible DBMS).
- Its core responsibility is to let developers construct SQL statements in a type‑safe, object‑oriented way, then compile them to SQL strings or execute them via PDO.

##### High‑Level Architecture and File Structure
- Top‑Level:
- composer.json / composer.lock – dependency & autoload config
- README.md – overview & usage
- src/ – library source code
- tests/ – PHPUnit test suite
- .github/ – CI & issue templates
- src/ Subfolders:
- Clauses/ – representations of SQL clauses (Where, GroupBy, OrderBy, Limit)
- Statements/ – statement types (Select, Insert, Update, Delete, plus base Statement)
- Exceptions/ – domain exceptions (InvalidQueryException, UnknownType)
- QueryBuilder.php – entry point & factory for statements
- Utils.php – helper functions used across classes

##### Core Components and Their Relationships
- QueryBuilder
- Factory & context holder (optionally stores a PDO instance & default fetch mode)
- Exposes .select(), .insertInto(), .update(), .deleteFrom()
- Returns a Statement object of the requested type
- Statement (abstract base)
- Owns a list of Clause objects (WHERE, GROUP BY, ORDER BY, LIMIT)
- Defines common methods: setParam(s), execute(), toSQL(), fetch(), rowCount(), getStatement()
- Concrete Statements
- Select, Insert, Update, Delete – each specializes .toSQL() and enforces statement‑specific rules
- Clauses
- Immutable clause objects (Where, OrderBy, GroupBy, Limit)
- Attached to statements via fluent calls: .where(), .orderBy(), .groupBy(), .limit()
- Utils
- String and array manipulations for generating SQL fragments
- Exceptions
- Thrown by QueryBuilder/Statement/Clauses when invalid queries or unsupported types are encountered
- External Service
- PDO – optional injection for direct query execution & fetching

##### Architectural Patterns and Design Principles
- Fluent Builder Pattern: chaining calls to incrementally build SQL
- Single Responsibility: each Statement and Clause class handles one part of the SQL grammar
- Open/Closed: users can extend by adding new Clause or Statement implementations and registering them
- Dependency Injection: optional PDO injection for testability and decoupling from global state

1. QueryBuilder (Factory)
2. Statement classes (Select, Insert, Update, Delete) inheriting from Statement
3. Clause classes (Where, GroupBy, OrderBy, Limit)
4. Utils (shared library)
5. Exceptions module
6. External PDO service
7. MySQL Database
- Relationships:
- QueryBuilder creates Statement instances
- Statement composes Clause instances
- Statement uses Utils to build SQL strings
- Statement optionally uses injected PDO to execute/fetch
- Statement may throw Exceptions back to the caller
- PDO connects to MySQL DB

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Factory Layer
    subgraph "Factory Layer"
        direction TB
        QB["QueryBuilder"]:::factory
    end

    %% Core Domain
    subgraph "Core Domain"
        direction TB
        ST["Statement (abstract)"]:::domain
        SEL["Select"]:::domain
        INS["Insert"]:::domain
        UPD["Update"]:::domain
        DEL["Delete"]:::domain
        subgraph "Clauses"
            direction TB
            WH["Where"]:::domain
            GB["GroupBy"]:::domain
            OB["OrderBy"]:::domain
            LM["Limit"]:::domain
        end
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        UT["Utils"]:::infra
        EXC["Exceptions"]:::infra
        PDO["PDO"]:::infra
        DB["MySQL Database"]:::infra
    end

    %% External Resources
    subgraph "Project Files & CI"
        direction TB
        COM["composer.json / composer.lock"]:::external
        RD["README.md"]:::external
        TS["tests/"]:::external
        CI1[".github/workflows/run-tests.yml"]:::external
        CI2[".github/workflows/create-release.yml"]:::external
    end

    %% Connections
    QB -->|"create()"| ST
    ST -->|"inherit"| SEL
    ST -->|"inherit"| INS
    ST -->|"inherit"| UPD
    ST -->|"inherit"| DEL

    ST -->|"addClause()"| WH
    ST -->|"addClause()"| GB
    ST -->|"addClause()"| OB
    ST -->|"addClause()"| LM

    ST -->|"uses build SQL"| UT
    ST -->|"execute()/fetch()"| PDO
    PDO -->|"JDBC/ODBC driver"| DB

    QB -.throws.-> EXC
    ST -.throws.-> EXC
    WH -.throws.-> EXC
    GB -.throws.-> EXC
    OB -.throws.-> EXC
    LM -.throws.-> EXC

    %% Autoload boundary
    COM --> QB
    COM --> ST
    COM --> UT
    COM --> EXC
    COM --> PDO
    TS --> QB
    TS --> ST
    RD --> COM
    CI1 --> TS
    CI2 --> TS

    %% Click Events
    click QB "https://github.com/iamludal/mysql-querybuilder/blob/develop/src/QueryBuilder.php"
    click ST "https://github.com/iamludal/mysql-querybuilder/blob/develop/src/Statements/Statement.php"
    click SEL "https://github.com/iamludal/mysql-querybuilder/blob/develop/src/Statements/Select.php"
    click INS "https://github.com/iamludal/mysql-querybuilder/blob/develop/src/Statements/Insert.php"
    click UPD "https://github.com/iamludal/mysql-querybuilder/blob/develop/src/Statements/Update.php"
    click DEL "https://github.com/iamludal/mysql-querybuilder/blob/develop/src/Statements/Delete.php"
    click WH "https://github.com/iamludal/mysql-querybuilder/blob/develop/src/Clauses/Where.php"
    click GB "https://github.com/iamludal/mysql-querybuilder/blob/develop/src/Clauses/GroupBy.php"
    click OB "https://github.com/iamludal/mysql-querybuilder/blob/develop/src/Clauses/OrderBy.php"
    click LM "https://github.com/iamludal/mysql-querybuilder/blob/develop/src/Clauses/Limit.php"
    click UT "https://github.com/iamludal/mysql-querybuilder/blob/develop/src/Utils.php"
    click EXC "https://github.com/iamludal/mysql-querybuilder/blob/develop/src/Exceptions/InvalidQueryException.php"
    click EXC "https://github.com/iamludal/mysql-querybuilder/blob/develop/src/Exceptions/UnknownType.php"
    click TS "https://github.com/iamludal/mysql-querybuilder/tree/develop/tests/"
    click COM "https://github.com/iamludal/mysql-querybuilder/blob/develop/composer.json"
    click RD "https://github.com/iamludal/mysql-querybuilder/blob/develop/README.md"
    click CI1 "https://github.com/iamludal/mysql-querybuilder/blob/develop/.github/workflows/run-tests.yml"
    click CI2 "https://github.com/iamludal/mysql-querybuilder/blob/develop/.github/workflows/create-release.yml"

    %% Styles
    classDef factory fill:#B2E5F7,stroke:#333,stroke-width:1px
    classDef domain fill:#F7D8BA,stroke:#333,stroke-width:1px
    classDef infra fill:#D1F7C4,stroke:#333,stroke-width:1px
    classDef external fill:#E2E2E2,stroke:#333,stroke-width:1px
```
