How homeruntech/closeio-api-wrapper works
Main system type and purpose
• This project is a PHP SDK / API client library for the Close.io REST services.
• Its goal is to let PHP applications instantiate API classes, send HTTP requests, and receive hydrated domain models.
Main components
a. Client Configuration
• Configuration holds API key, base URL, default headers.
b. HTTP Transport Layer
• Httplug Client (PSR-18 / PSR-7 implementation) (e.g., nyholm/psr7 + php-http/curl-client)
• ClientInterface and its concrete Client implementation use Httplug to send PSR-7 Requests and receive PSR-7 Responses.
c. Facade / Wrapper
• CloseIoApiWrapper exposes top-level getXxxApi() methods (LeadApi, OpportunityApi, ActivityApi, etc.).
d. API Modules (src/Api)
• Each API class (e.g., LeadApi, OpportunityApi, etc.) extends Library\Api\AbstractApi.
• These modules build HTTP requests, call the Client, and wrap raw responses.
e. Domain Models (src/Model)
• Plain PHP objects (Lead, Contact, Task, etc.) with getters/setters.
f. Hydration & Utilities (src/Library)
• Traits and helpers (JsonSerializableHelperTrait, ObjectHydrateHelperTrait, UrlUtils, InflectorSingleton) that translate raw JSON into Model instances.
g. Exception Hierarchy (src/Exception)
• Custom exceptions (authentication, throttling, bad request, not found, etc.) thrown by the HTTP layer or API modules.
h. External Service
• The Close.io REST API (an external HTTP endpoint).
Relationships and data flows
• External App calls → CloseIoApiWrapper → chooses an Api module
• Api module uses → Client via ClientInterface → constructs a PSR-7 Request using Configuration
• Client sends → HTTP request over the network via Httplug → receives PSR-7 Response
• Api module inspects status code → throws mapped exceptions if needed → extracts JSON body
• JSON is passed to → Hydration helpers → produces PHP Model objects
• Api returns hydrated Model or a wrapper (CloseIoResponse) to External App
Architectural patterns and principles
• Facade Pattern: CloseIoApiWrapper unifies all API modules.
• Adapter Pattern: Httplug decouples HTTP client implementations.
• Single Responsibility: Separate layers for configuration, transport, API logic, model hydration, and exceptions.
• PSR-7 / PSR-18 Compliance: Interfaces standardize HTTP messages and clients.
Essential elements to capture
• Clear separation: Facade vs. Api modules vs. Transport vs. Model/Hydration vs. Exceptions
• PSR interfaces as boundaries
• Configuration’s role in building requests
• The external service as the system’s sink/source