# quintoche/discite-php architecture

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

- Interactive diagram: https://gitdiagram.com/quintoche/discite-php
- Repository: https://github.com/quintoche/discite-php

## Overview

##### Project type and purpose
- This is an open-source PHP library (Discite-PHP) implementing a MySQLi-based, fluent, object-oriented query builder.
- Its purpose is to give PHP applications a modular, secure, configurable API to construct, format, execute, and retrieve SQL queries without hand-crafting SQL strings.

##### File structure
- Top-level directories:
- src/ — core library organized under DisciteDB namespace
- example/ — sample scripts demonstrating usage
- tests/ — PHPUnit test cases
- Under src/DisciteDB:
- Config — configuration definitions and enums
- Core — managers (QueryManager, TablesManager, etc.)
- Connection, Database, DisciteDB entry classes
- QueryHandler — builder, handlers, result classes
- Sql — clause/data/format/loading submodules
- Fields, Keys, Methods (condition, modifier), Operators, Security, Utilities, Exceptions
- Config files, traits, and enums show extensibility points; QueryHandler + Sql modules implement the builder and SQL formatting.

##### README insights
- External dependency: a MySQLi connection supplied by the host application
- Features: injection protection, modular configuration (charset, collation, naming, joins, etc.), strict/loose modes, key/table definitions
- Usage pattern: Application → Database class → Configuration → table(…) → listing() / count() → fetchAll()/fetchQuery()

a. Main components
1. Application Code
2. DisciteDB Entry Points
- Database (connection wrapper)
- DisciteDB (static constants)
3. Configuration Module
- Config classes & Enums
- Traits for KeysManager, TablesManager, LogsManager
4. Core Managers
- QueryManager
- TablesManager
- UsersManager, KeysManager, LogsManager
- SecurityManager, DebugManager, ExceptionsManager
5. Query Handler & Builder
- QueryBuilder, Handler classes (Argument, Structure, Template, Join, Modifier)
6. SQL Generator & Formatter
- Clause, Data, Format submodules under Sql/
7. Execution Layer
- Connection (wraps MySQLi)
- QueryHandler→QueryResult
8. Result Handling
- Result, ResultData, ResultInformations, ResultAsync
9. Utilities & Exceptions
- NameSanitizer, ValidateJson
- Exceptions hierarchy
10. External MySQL Server
b. Relationships & interactions
1. App calls Database($mysqli) → returns Database instance
2. App configures via Database->configuration() → updates Config module
3. App invokes table('name')->listing(…) → QueryManager uses Config to validate keys/tables
4. QueryManager constructs an abstract query representation using QueryHandler
5. QueryHandler delegates to Clause/Data/Format classes to generate SQL string
6. Generated SQL passes to Connection for execution on MySQL
7. MySQL response flows back into QueryResult classes → App fetches rows/information
8. SecurityManager & DebugManager intercept as configured (CSRF, sanitize, logs)
9. ExceptionsManager handles any errors from connection, query, or security violations
c. Architectural patterns & design principles
- Fluent Interface / Builder pattern (QueryBuilder)
- Modular configuration (Strategy via Config enums)
- Separation of Concerns: Connection vs. QueryBuilding vs. Formatting vs. Execution vs. Result
- Extensibility via Traits and Interfaces (custom keys, tables, handlers)
- Single Responsibility for each Manager and Handler
d. Key technologies, frameworks, libraries
- PHP (namespaces, Composer autoload)
- MySQLi (native PHP extension)
- PHPUnit (tests)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External
    App["Application"]:::external

    %% Entry Points
    subgraph "Entry & Connection" 
        Database["Database"]:::entry
        DisciteDBConst["DisciteDB (static)"]:::entry
        Connection["Connection"]:::entry
        Configuration["Configuration"]:::entry
    end

    %% Configuration Module
    subgraph "Configuration Module"
        ConfigDefaults["Default Config"]:::config
        ConfigEnums["Config Enums"]:::config
        TraitKeys["KeysManager Trait"]:::config
        TraitTables["TablesManager Trait"]:::config
        TraitLogs["LogsManager Trait"]:::config
    end

    %% Core Managers
    subgraph "Core Managers"
        QueryManager["QueryManager"]:::core
        TablesManager["TablesManager"]:::core
        KeysManagerCore["KeysManager"]:::core
        LogsManagerCore["LogsManager"]:::core
        SecurityManager["SecurityManager"]:::core
        DebugManager["DebugManager"]:::core
        ExceptionsManager["ExceptionsManager"]:::core
        UsersManager["UsersManager"]:::core
    end

    %% Query Builder & Handlers
    subgraph "Query Handler & Builder"
        QueryBuilder["QueryBuilder"]:::builder
        QueryHandlerCore["QueryHandler"]:::builder
        IndividualHandlers["Individual Handlers"]:::builder
    end

    %% SQL Generation
    subgraph "SQL Generator & Formatter"
        ClauseBuilders["Clause Builders"]:::sql
        DataFormatters["Data Formatters"]:::sql
        SQLFormatters["SQL Formatters"]:::sql
        LoadingStrategies["Loading Strategies"]:::sql
    end

    %% Execution & Results
    subgraph "Execution & Result Handling"
        QueryResult["QueryResult"]:::exec
        AbstractResult["AbstractResult"]:::exec
        ResultSync["Result (sync)"]:::exec
        ResultAsync["Result (async)"]:::exec
        ResultData["ResultData"]:::exec
        ResultInfo["ResultInformations"]:::exec
        ResultExceptions["ResultExceptions"]:::exec
    end

    %% Utilities & Exceptions
    subgraph "Utilities & Exceptions"
        NameSanitizer["NameSanitizer"]:::util
        ValidateJson["ValidateJson"]:::util
        ExceptionsHierarchy["Exceptions Hierarchy"]:::util
    end

    %% Models & Others
    subgraph "Fields, Methods, Operators, Models, Security"
        Fields["Fields"]:::util
        ConditionHandlers["Condition Handlers"]:::util
        MethodHandlers["Method Handlers"]:::util
        ModifierHandlers["Modifier Handlers"]:::util
        OperatorsModule["Operators"]:::util
        TablesModel["Tables Model"]:::util
        KeysModel["Keys Model"]:::util
        UsersModel["Users Model"]:::util
        SecurityModule["Security Module"]:::util
    end

    %% External Database
    MySQL["MySQL Server"]:::external_db

    %% Connections
    App -->|"init"| Database
    App -->|"use static"| DisciteDBConst
    Database -->|"wrap mysqli"| Connection
    Database -->|"load config"| Configuration
    Configuration --> ConfigDefaults
    Configuration --> ConfigEnums
    Configuration --> TraitKeys
    Configuration --> TraitTables
    Configuration --> TraitLogs
    ConfigEnums --> QueryManager
    TraitKeys --> KeysManagerCore
    TraitTables --> TablesManager
    TraitLogs --> LogsManagerCore

    QueryManager -->|"orchestrate"| QueryBuilder
    QueryManager -->|"call handlers"| QueryHandlerCore
    QueryHandlerCore --> IndividualHandlers

    QueryBuilder --> ClauseBuilders
    QueryBuilder --> DataFormatters
    QueryBuilder --> SQLFormatters
    QueryBuilder --> LoadingStrategies

    SQLFormatters -->|"generate SQL"| Connection
    Connection -->|"execute"| MySQL
    MySQL -->|"response"| QueryResult
    QueryResult --> AbstractResult
    AbstractResult --> ResultSync
    AbstractResult --> ResultAsync
    QueryResult --> ResultData
    QueryResult --> ResultInfo
    QueryResult --> ResultExceptions
    ResultSync --> App
    ResultAsync --> App

    SecurityManager -->|intercept| Connection
    DebugManager -->|log| Connection
    ExceptionsManager -->|handle errors| Connection

    NameSanitizer --> QueryBuilder
    ValidateJson --> Configuration
    ExceptionsHierarchy --> ExceptionsManager

    Fields --> QueryBuilder
    ConditionHandlers --> QueryBuilder
    MethodHandlers --> QueryBuilder
    ModifierHandlers --> QueryBuilder
    OperatorsModule --> QueryBuilder
    TablesModel --> TablesManager
    KeysModel --> KeysManagerCore
    UsersModel --> UsersManager
    SecurityModule --> SecurityManager

    %% Click Events
    click Database "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/Database.php"
    click DisciteDBConst "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/DisciteDB.php"
    click Connection "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/Connection.php"
    click Configuration "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/Configuration.php"
    click ConfigDefaults "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Config/Default/"
    click ConfigEnums "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Config/Enums/"
    click TraitKeys "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Config/Traits/KeysManager/"
    click TraitTables "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Config/Traits/TablesManager/"
    click TraitLogs "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Config/Traits/LogsManager/"
    click QueryManager "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/Core/QueryManager.php"
    click TablesManager "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/Core/TablesManager.php"
    click KeysManagerCore "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/Core/KeysManager.php"
    click LogsManagerCore "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/Core/LogsManager.php"
    click SecurityManager "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/Core/SecurityManager.php"
    click DebugManager "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/Core/DebugManager.php"
    click ExceptionsManager "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/Core/ExceptionsManager.php"
    click UsersManager "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/Core/UsersManager.php"
    click QueryBuilder "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/QueryHandler/QueryBuilder.php"
    click QueryHandlerCore "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/QueryHandler/QueryHandler.php"
    click IndividualHandlers "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/QueryHandler/Handler/"
    click ClauseBuilders "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Sql/Clause/"
    click DataFormatters "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Sql/Data/"
    click SQLFormatters "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Sql/Format/"
    click LoadingStrategies "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Sql/Loading/"
    click QueryResult "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/QueryHandler/QueryResult.php"
    click AbstractResult "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/QueryHandler/Result/AbstractResult.php"
    click ResultSync "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/QueryHandler/Result/Result.php"
    click ResultAsync "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/QueryHandler/Result/ResultAsync.php"
    click ResultData "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/QueryHandler/Result/ResultData.php"
    click ResultInfo "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/QueryHandler/Result/ResultInformations.php"
    click ResultExceptions "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/QueryHandler/Result/ResultExceptions.php"
    click NameSanitizer "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/Utilities/NameSanitizer.php"
    click ValidateJson "https://github.com/quintoche/discite-php/blob/main/src/DisciteDB/Utilities/ValidateJson.php"
    click ExceptionsHierarchy "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Exceptions/"

    click Fields "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Fields/"
    click ConditionHandlers "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Methods/ConditionHandlers/"
    click MethodHandlers "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Methods/MethodHandlers/"
    click ModifierHandlers "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Methods/ModifierHandlers/"
    click OperatorsModule "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Operators/"
    click TablesModel "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Tables/"
    click KeysModel "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Keys/"
    click UsersModel "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Users/"
    click SecurityModule "https://github.com/quintoche/discite-php/tree/main/src/DisciteDB/Security/"

    %% Styles
    classDef entry fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef config fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef core fill:#d4edda,stroke:#28a745,color:#155724;
    classDef builder fill:#ffe5b4,stroke:#ff8c00,color:#804000;
    classDef sql fill:#ffe5b4,stroke:#ff8c00,color:#804000;
    classDef exec fill:#e2e3e5,stroke:#6f42c1,color:#ffffff;
    classDef util fill:#f8f9fa,stroke:#6c757d,color:#212529;
    classDef external fill:#d1ecf1,stroke:#17a2b8,color:#0c5460;
    classDef external_db fill:#f8d7da,stroke:#dc3545,color:#721c24;
```
