# thephpleague/geotools architecture

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

- Interactive diagram: https://gitdiagram.com/thephpleague/geotools
- Repository: https://github.com/thephpleague/geotools

## Overview

##### Project Type and Purpose
- Geotools is a standalone, open‑source PHP library (not a web app) exposing geo‑related services (coordinate normalization, conversion, distance, vertex calculations, geohashing, polygon tests) and a CLI tool for end users.
- It integrates with external geocoding providers via the Geocoder library, runs batch jobs via ReactPHP, and uses Symfony’s Console for its CLI.

##### File Structure
- Top‑level “bin/geotools”: the PHP CLI entry point.
- “src/”: core library organized into feature folders:
–  Coordinate (Coordinate, Ellipsoid, collections)
–  Convert (ConvertInterface, Convert)
–  Distance (DistanceInterface, Distance)
–  Vertex (bearing, cardinal, middle, destination)
–  Geohash (encode/decode, neighbor calculations)
–  Batch (series/parallel geocoding with caching)
–  Polygon & BoundingBox
–  CLI (Symfony commands under src/CLI/Command, GeotoolsApplication, OutputFormatter)
–  Exceptions, ArrayCollection, GeometryInterface
- Composer files, PSR‑4 autoload, PHPUnit config, CI workflows, docs, tests mirror src/.

##### Extract Architectural Insights from the README
- Geotools offers a Facade/API class (`\League\Geotools\Geotools`) that instantiates and delegates to each subsystem.
- Batch geocoding uses an event loop (ReactPHP), a provider aggregator (Geocoder), and PSR‑6 cache adapters.
- CLI commands live in Symfony’s Command pattern, share a common Application class and OutputFormatter.
- Conversion, distance, vertex, geohash, polygon each encapsulate discrete algorithms behind interfaces.

##### Main Components
a.  CLI Layer
–  Bin script “geotools” → Symfony Console Application
–  Commands: distance:*, convert:*, point:*, geohash:*, batch:*, geocoder:*
b.  Core Library Facade
–  `Geotools` façade → exposes convert(), distance(), vertex(), geohash(), batch(), polygon()
–  Convert Module (Convert, ConvertInterface)
–  Distance Module (Distance, DistanceInterface)
–  Vertex Module (Vertex, VertexInterface)
–  Geohash Module (Geohash, GeohashInterface, TenTen)
–  Polygon Module (Polygon, BoundingBox)
–  Batch Module (Batch, BatchInterface, BatchResult, uses Geocoder + ReactPHP)
–  Coordinate Module (Coordinate, Ellipsoid)
d.  External Dependencies
–  Geocoder Provider Aggregator → HTTP Client (HTTPlug/Discovery)
–  ReactPHP Event Loop
–  PSR‑6 Cache Pool (e.g. Redis, ArrayCache)
–  Symfony Console & Serializer
e.  Tests / CI
–  PHPUnit suite (tests/)
–  GitHub Actions / Scrutinizer CI

##### Relationships & Data Flow
- CLI Command → Application → Geotools façade → Feature Module → Domain Objects (Coordinate, Ellipsoid)
- Batch Module → dispatches tasks to Geocoder Provider(s) via HTTP Client → optionally caches via PSR‑6 → returns BatchResult
- Convert/Distance/Vertex/Geohash/Polygon modules operate purely on Coordinate/Ellipsoid domain objects
- All modules use common Exception types, share ArrayCollection where needed

##### Architectural Patterns & Principles
- Facade Pattern: single entry point (`Geotools`)
- Command Pattern: Symfony Console Commands
- Interface‑based design: each module has Interface + Implementation
- Adapter Pattern: PSR‑6 cache, HTTPlug HTTP client, Geocoder providers, Symfony Serializer
- Separation of Concerns: each folder is a discrete service
- Event‑driven: ReactPHP for parallel batch processing

##### Essential Elements
- Clear component labels and namespaces
- Call out key interfaces and extension points (e.g. `ConvertInterface`, `BatchInterface`, `GeohashInterface`)

– Captures the high‑level flow from user (CLI or code) into core services.
– Exposes each feature module and its interface.
– Shows how external libraries (Geocoder, ReactPHP, PSR‑6, Symfony Console) integrate.
– Highlights where and how to extend or customize the system.
Grouping related classes, showing clear data paths, and annotating extension/adapter boundaries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLIEntry["bin/geotools"]:::cli
        App["League\\Geotools\\CLI\\GeotoolsApplication"]:::cli
        CommandsFolder["src/CLI/Command/"]:::cli
        Formatter["League\\Geotools\\CLI\\Formatter\\OutputFormatter"]:::cli
        ConsoleOut["League\\Geotools\\CLI\\Output\\ConsoleOutput"]:::cli
    end

    %% Core Library Facade and Feature Modules
    subgraph "Core Library" 
        direction TB
        FacadeInterface["League\\Geotools\\GeotoolsInterface"]:::core
        FacadeImpl["League\\Geotools\\Geotools"]:::core

        subgraph "Feature Modules"
            direction TB
            ConvertMod["League\\Geotools\\Convert\\Convert"]:::core
            DistanceMod["League\\Geotools\\Distance\\Distance"]:::core
            VertexMod["League\\Geotools\\Vertex\\Vertex"]:::core
            GeohashMod["League\\Geotools\\Geohash\\Geohash"]:::core
            PolygonMod["League\\Geotools\\Polygon\\Polygon"]:::core
            BoundingBoxMod["League\\Geotools\\BoundingBox\\BoundingBox"]:::core
            BatchMod["League\\Geotools\\Batch\\Batch"]:::core
            CoordinateMod["League\\Geotools\\Coordinate\\Coordinate"]:::core
        end

        Collection["League\\Geotools\\ArrayCollection"]:::core
        Geometry["League\\Geotools\\GeometryInterface"]:::core
        Exceptions["src/Exception/"]:::core
    end

    %% External Dependencies
    subgraph "External Services & Adapters"
        direction TB
        Geocoder["Geocoder Provider Aggregator"]:::external
        HTTPClient["HTTPlug/Discovery HTTP Client"]:::external
        EventLoop["ReactPHP Event Loop"]:::external
        Cache["PSR-6 Cache Pool"]:::external
        SymfonyConsole["Symfony Console"]:::external
        Serializer["Symfony Serializer"]:::external
    end

    %% CI and Tests
    subgraph "Tests & CI"
        direction TB
        PHPUnit["tests/"]:::ci
        CIWorkflow[".github/workflows/ci.yml"]:::ci
        Scrutinizer[".scrutinizer.yml"]:::ci
        Composer["composer.json"]:::ci
        Docs["README.md / docs"]:::ci
    end

    %% Connections
    CLIEntry -->|"executes"| App
    App -->|"runs commands"| CommandsFolder
    CommandsFolder -->|"calls facade"| FacadeImpl
    App -->|".getOutput()"| ConsoleOut
    App -->|".getFormatter()"| Formatter

    FacadeImpl -->|"implements"| FacadeInterface
    FacadeImpl -->|"delegates to"| ConvertMod
    FacadeImpl -->|"delegates to"| DistanceMod
    FacadeImpl -->|"delegates to"| VertexMod
    FacadeImpl -->|"delegates to"| GeohashMod
    FacadeImpl -->|"delegates to"| PolygonMod
    FacadeImpl -->|"delegates to"| BoundingBoxMod
    FacadeImpl -->|"delegates to"| BatchMod
    FacadeImpl -->|"uses"| CoordinateMod

    BatchMod -->|"uses"| EventLoop
    BatchMod -->|"uses"| Geocoder
    Geocoder -->|"via HTTP"| HTTPClient
    BatchMod -->|"caches via"| Cache
    SymfonyConsole -->|"supports CLI"| App
    Serializer -->|"formats output"| Formatter

    ConvertMod -->|"uses"| Collection
    DistanceMod -->|"uses"| Collection
    VertexMod -->|"uses"| Collection
    GeohashMod -->|"uses"| Collection
    PolygonMod -->|"uses"| Collection
    BoundingBoxMod -->|"uses"| Collection
    CoordinateMod -->|"defines"| Geometry
    Exceptions -->|"thrown by"| FacadeImpl
    Exceptions -->|"thrown by"| ConvertMod

    PHPUnit -->|"tests mirror"| src
    CIWorkflow -->|"runs"| PHPUnit
    CIWorkflow -->|"runs"| Scrutinizer
    Composer -->|"defines autoload"| src
    Docs -->|"documents"| FacadeImpl

    %% Click Events
    click CLIEntry "https://github.com/thephpleague/geotools/tree/master/bin/geotools"
    click App "https://github.com/thephpleague/geotools/blob/master/src/CLI/GeotoolsApplication.php"
    click CommandsFolder "https://github.com/thephpleague/geotools/tree/master/src/CLI/Command/"
    click Formatter "https://github.com/thephpleague/geotools/blob/master/src/CLI/Formatter/OutputFormatter.php"
    click ConsoleOut "https://github.com/thephpleague/geotools/blob/master/src/CLI/Output/ConsoleOutput.php"
    click FacadeInterface "https://github.com/thephpleague/geotools/blob/master/src/GeotoolsInterface.php"
    click FacadeImpl "https://github.com/thephpleague/geotools/blob/master/src/Geotools.php"
    click ConvertMod "https://github.com/thephpleague/geotools/blob/master/src/Convert/Convert.php"
    click DistanceMod "https://github.com/thephpleague/geotools/blob/master/src/Distance/Distance.php"
    click VertexMod "https://github.com/thephpleague/geotools/blob/master/src/Vertex/Vertex.php"
    click GeohashMod "https://github.com/thephpleague/geotools/blob/master/src/Geohash/Geohash.php"
    click PolygonMod "https://github.com/thephpleague/geotools/blob/master/src/Polygon/Polygon.php"
    click BoundingBoxMod "https://github.com/thephpleague/geotools/blob/master/src/BoundingBox/BoundingBox.php"
    click BatchMod "https://github.com/thephpleague/geotools/blob/master/src/Batch/Batch.php"
    click CoordinateMod "https://github.com/thephpleague/geotools/blob/master/src/Coordinate/Coordinate.php"
    click Exceptions "https://github.com/thephpleague/geotools/tree/master/src/Exception/"
    click PHPUnit "https://github.com/thephpleague/geotools/tree/master/tests/"
    click CIWorkflow "https://github.com/thephpleague/geotools/blob/master/.github/workflows/ci.yml"
    click Scrutinizer "https://github.com/thephpleague/geotools/blob/master/.scrutinizer.yml"
    click Composer "https://github.com/thephpleague/geotools/blob/master/composer.json"
    click Docs "https://github.com/thephpleague/geotools/blob/master/README.md"

    %% Styles
    classDef cli fill:#D6BCF5,stroke:#805AD5,color:#1A202C;
    classDef core fill:#BEE3F8,stroke:#4299E1,color:#1A202C;
    classDef external fill:#C6F6D5,stroke:#38A169,color:#1A202C;
    classDef ci fill:#FEEBC8,stroke:#DD6B20,color:#1A202C;
```
