How thephpleague/geotools works
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.