# mickeywaugh/captcha architecture

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

- Interactive diagram: https://gitdiagram.com/mickeywaugh/captcha
- Repository: https://github.com/mickeywaugh/captcha

## Overview

##### Main Components
- Phrase Builder Component – Show the PhraseBuilder class (and its interface) as a subcomponent used by the CaptchaBuilder. Its role is to generate the captcha text (or “phrase”), optionally allowing customization (e.g., character count, specific character sets).
- Image File Handler – Represent the ImageFileHandler, which likely manages file operations (saving, reading, outputting image data).
- Demo/Client Examples – Although provided in the demo folder, illustrate how client code (demo scripts such as index.php, form.php, session.php, etc.) interacts with the core components to render a captcha in various formats (save as file, inline in HTML, or output directly).
- Testing Component – Optionally include the test suite (tests folder) to emphasize that the system is built with unit testing considerations (like the CaptchaBuilderTest).

##### Relationships and Interactions
- The Client (demo code or external application code) instantiates the CaptchaBuilder.
- The CaptchaBuilder calls the PhraseBuilder for generating the captcha phrase.
- The CaptchaBuilder optionally interacts with the ImageFileHandler to save or output the generated image.
- If OCR testing is enabled (using methods like buildAgainstOCR), an external dependency on system tools (e.g., PHP’s shell_exec, ImageMagick, and ocrad) should be indicated.

##### Architectural Patterns and Key Design Principles
- Object-Oriented Design – Note that the project relies on OOP (see the classes and interfaces) and clearly applies dependency/inversion principles by using interfaces (CaptchaBuilderInterface, PhraseBuilderInterface).
- Separation of Concerns – Emphasize how generating the captcha (logic, phrase, image handling) is divided across dedicated classes, making the library modular and extensible.
- Extensibility – The README and structure suggest that the library is designed to work both as a stand-alone captcha generator and via extensions (e.g., Symfony Bundle, Yii2 extension), so include a mention of integration points for these frameworks.

##### Relevant Technologies and Frameworks
- PHP (core language and OOP)
- Composer (dependency management, indicated in composer.json)
- External libraries/tools: GD or ImageMagick for image manipulation, OCR tools for read-related functionality.
- Testing frameworks (PHPUnit as referenced in phpunit.xml.dist)
- Integrations for Symfony and Yii2 via dedicated bundles/extensions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        client["Demo/Client Code"]:::client
    end

    subgraph "Core Library Components"
        CB["CaptchaBuilder"]:::library
        CBIF["CaptchaBuilderInterface"]:::library
        PB["PhraseBuilder"]:::library
        PBIF["PhraseBuilderInterface"]:::library
        IFH["ImageFileHandler"]:::library
        FR["Font Resources"]:::library
    end

    subgraph "External & Integration"
        ext["OCR/Image Tools"]:::external
        ip["Integration (Symfony/Yii2)"]:::integration
    end

    subgraph "Testing Suite"
        test["CaptchaBuilderTest"]:::testing
    end

    %% Relations
    client -->|"instantiates"| CB
    CB -.->|"implements"| CBIF
    PB -.->|"implements"| PBIF
    CB -->|"callsPhraseBuilder"| PB
    CB -->|"handlesImageOutput"| IFH
    CB -->|"utilizesFont"| FR
    CB -->|"callsOCR"| ext
    ip -->|"integratesWith"| CB
    test -->|"tests"| CB

    %% Click Events
    click CB "https://github.com/mickeywaugh/captcha/blob/master/src/Gregwar/Captcha/CaptchaBuilder.php"
    click CBIF "https://github.com/mickeywaugh/captcha/blob/master/src/Gregwar/Captcha/CaptchaBuilderInterface.php"
    click PB "https://github.com/mickeywaugh/captcha/blob/master/src/Gregwar/Captcha/PhraseBuilder.php"
    click PBIF "https://github.com/mickeywaugh/captcha/blob/master/src/Gregwar/Captcha/PhraseBuilderInterface.php"
    click IFH "https://github.com/mickeywaugh/captcha/blob/master/src/Gregwar/Captcha/ImageFileHandler.php"
    click FR "https://github.com/mickeywaugh/captcha/tree/master/src/Gregwar/Captcha/Font"
    click client "https://github.com/mickeywaugh/captcha/tree/master/demo"
    click test "https://github.com/mickeywaugh/captcha/blob/master/tests/CaptchaBuilderTest.php"

    %% Styles
    classDef client fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef library fill:#c8e6c9,stroke:#1b5e20,stroke-width:2px;
    classDef external fill:#ffcdd2,stroke:#b71c1c,stroke-width:2px;
    classDef integration fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef testing fill:#f0f4c3,stroke:#9e9d24,stroke-width:2px;
```
