How yousseftamri/openai-php works
Project Type and Purpose
• This is a PHP SDK (API client library) for OpenAI’s REST API. It is neither a web application nor a microservice but an SDK you embed in user code.
Main Architectural Layers and Components
A. Public API Layer (blue)
• Factory (OpenAI\Factory)
• Builder pattern: configures API key, base URI, HTTP client, headers, query params.
• .make() → returns Client.
• Client (OpenAI\Client)
• Façade exposing methods: chat(), completions(), models(), files(), etc.
• Implements ClientContract.
• Resources (OpenAI\Resources\*)
• One class per endpoint group (Chat, Completions, Images, Threads, VectorStores…).
• Expose high-level methods (create(), list(), retrieve(), delete(), createStreamed(), etc).
B. Domain / Contracts Layer (orange)
• Contracts (OpenAI\Contracts\*)
• Interfaces: ClientContract, TransporterContract, ResourceContracts, ResponseContract, ResponseStreamContract, StringableContract.
• Enums (OpenAI\Enums\*)
• Typed constants for content types, HTTP methods, moderation categories, fine-tuning event levels.
• ValueObjects (OpenAI\ValueObjects\*)
• ApiKey, BaseUri, Headers, QueryParams, Payload, Response: encapsulate raw data.
C. Transport / Infrastructure Layer (green)
• Transporter: HttpTransporter (implements TransporterContract)
• Uses PSR-18 HTTP client (e.g. Guzzle).
• Builds PSR-7 Request from ValueObjects.
• Sends HTTP, receives PSR-7 Response.
• Wraps in ValueObjects\Transporter\Response for downstream.
• HTTP Client (external): e.g. GuzzleHttp\Client, injected via PSR-18 Discovery or manually.
D. Response Mapping Layer
• Responses (OpenAI\Responses\*)
• One sub-namespace per resource.
• JSON keys into strongly typed objects (choices, usage, segments, events, etc).
• Support meta-information: rate limits, request IDs.
• Exceptions (OpenAI\Exceptions\*)
• ErrorException, TransporterException, InvalidArgumentException, UnknownEventException, etc.
E. Testing Layer (gray)
• ClientFake (OpenAI\Testing\ClientFake)
• Implements ClientContract, bypasses HTTP, returns prebuilt fakes or fixtures from src/Testing or tests/Fixtures.
• Allows assertions on sent requests.
Component Relationships and Data Flow
1. User Code calls OpenAI\Factory → configures and builds an OpenAI\Client.
2. Client.method() delegates to a Resource instance.
3. Resource prepares parameters and invokes Transporter->send().
4. Transporter:
• Assembles PSR-7 Request (ValueObjects: ApiKey, Headers, BaseUri, QueryParams, Payload)
• Calls HTTP client → hits OpenAI REST API endpoint.
• Receives PSR-7 Response → wraps into ValueObjects\Response.
5. Resource decodes JSON → instantiates Response objects (e.g., CreateResponse, ListResponse, StreamedResponse).
6. User code consumes typed response.
7. On error, Exceptions bubble up.
Architectural Patterns and Principles
• Dependency Injection: HTTP client, headers, query params injected via Factory.
• Facade Pattern: Client and Resources hide low-level HTTP details.
• Strategy/Adapter: TransporterContract allows swapping HTTP implementations.
• Factory/Builder: Factory for client configuration.
• Interface Segregation: Contracts for each module → clear DIP.