Skip to content

Overview

Purpose and Goals

The Instructor HTTP client API is designed to provide a consistent interface for making HTTP requests across different PHP environments.

It provides a single API regardless of the underlying HTTP client available in the given environment, which may be Symfony, Laravel, Slim, or just vanilla PHP.

The primary goals of the API are:

  • Easily Switch Between HTTP Clients: Allow developers to switch between different HTTP client libraries (like Guzzle, Symfony, and Laravel) without changing the code that makes HTTP requests
  • Framework Agnostic: Work seamlessly in Laravel, Symfony, or any PHP application without framework-specific dependencies
  • Consistent Interface: Provide a one way to make HTTP requests regardless of the underlying client library
  • Middleware Support: Enable easy extension through a powerful middleware system
  • Adaptability: Allow switching between different HTTP client implementations with minimal code changes
  • Streaming Support: Provide first-class support for streaming responses, which is crucial for LLM interactions
  • Concurrency: Support parallel requests through request pooling

By abstracting away the differences between various HTTP client libraries, the Instructor works across different environments and frameworks without modification.

Key Features

Multiple Client Support

The API supports multiple HTTP client libraries through specialized drivers:

  • Guzzle: A popular and feature-rich HTTP client for PHP
  • Symfony HTTP Client: The HTTP client component from the Symfony framework
  • Laravel HTTP Client: The HTTP client built into the Laravel framework

Middleware System

A powerful middleware architecture allows for:

  • Request Pre-processing: Modify requests before they are sent
  • Response Post-processing: Transform or analyze responses
  • Response Streaming: Process streaming responses chunk by chunk
  • Debugging: Log requests and responses for troubleshooting
  • Custom Behaviors: Add specialized behaviors like caching or rate limiting

Streaming Response Support

First-class support for streaming HTTP responses, which is essential for:

  • LLM Text Generation: Process token-by-token responses from AI models
  • Large File Downloads: Handle large files without excessive memory usage
  • Real-time Data: Process server-sent events or other real-time data streams

Request Pooling

Execute multiple HTTP requests concurrently for better performance:

  • Concurrent Execution: Send multiple requests in parallel
  • Configurable Concurrency: Control the maximum number of concurrent requests
  • Result Collection: Process results as they arrive
  • Error Handling: Flexible error handling strategies

Flexible Configuration

Comprehensive configuration options:

  • Per-Client Configuration: Different settings for each client type
  • Named Configurations: Multiple configurations for different use cases
  • Runtime Configuration: Change configuration during execution
  • Timeout Controls: Fine-grained control over various timeout settings

Debug and Testing Support

Built-in features for debugging and testing:

  • Request/Response Logging: Detailed logging of HTTP interactions
  • Mock Client: Test your code without making actual HTTP requests
  • Record/Replay: Record HTTP interactions and replay them later

Architecture Overview

The Instructor HTTP client follows a layered architecture with several key components:

Client Layer

The HttpClient class serves as the main entry point and provides a fluent interface for configuring and using the HTTP client.

HttpClient
  └── using() - Create client with specific configuration (static)
  └── default() - Create client with default configuration (static)
  └── withMiddleware() - Add middleware components
  └── withMiddlewareStack() - Replace entire middleware stack
  └── withoutMiddleware() - Remove middleware by name
  └── withRequest() - Create pending request for execution
  └── pool() - Execute multiple requests concurrently
  └── withPool() - Create pending pool for deferred execution

Middleware Layer

The middleware system allows for processing requests and responses through a chain of handlers:

Request -> Middleware 1 -> Middleware 2 -> ... -> Driver -> External API
                                                   ↓
Response <- Middleware 1 <- Middleware 2 <- ... <- Driver <- HTTP Response

Key components: - MiddlewareStack: Manages the collection of middleware - MiddlewareHandler: Orchestrates the middleware chain execution - BaseMiddleware: Base class for implementing middleware

Driver Layer

Drivers implement the CanHandleHttpRequest interface and adapt different HTTP client libraries:

CanHandleHttpRequest (interface)
  ├── GuzzleDriver
  ├── SymfonyDriver
  ├── LaravelDriver
  └── MockHttpDriver (for testing)

Adapter Layer

Response adapters convert client-specific responses to a common interface:

HttpResponse (interface)
  ├── PsrHttpResponse (Guzzle)
  ├── SymfonyHttpResponse
  ├── LaravelHttpResponse
  └── MockHttpResponse

Supported HTTP Clients

Guzzle HTTP Client

The Guzzle HTTP Client is a powerful HTTP client library for PHP. It provides:

  • PSR-7 HTTP message implementation
  • Middleware system
  • Request and response plugins
  • HTTP/2 support (via cURL)

The GuzzleDriver adapts Guzzle to the Instructor HTTP client API interface.

Symfony HTTP Client

The Symfony HTTP Client is a component of the Symfony framework. Features include:

  • HTTP/2 push support
  • PSR-18 compatibility
  • Automatic content-type detection
  • Proxy support

The SymfonyDriver adapts the Symfony HTTP Client to the Instructor HTTP client API.

Laravel HTTP Client

The Laravel HTTP Client is built into the Laravel framework and provides:

  • Fluent, readable syntax
  • Request macros
  • Automatic JSON handling
  • Rate limiting
  • Retry logic

The LaravelDriver adapts the Laravel HTTP Client to the Instructor HTTP client API.

Mock HTTP Driver

The MockHttpDriver provides a test double for unit testing. It doesn't make actual HTTP requests but returns predefined responses based on matching rules.