v2: Middleware Architecture and Fluent API

[parsilver]

Summary

This PR introduces version 2 of the Transport library with a complete architectural redesign. The new version features a middleware pipeline architecture, fluent API for building requests, and advanced retry strategies with exponential backoff.

Key Features

✅ Middleware Architecture - Extensible plugin system for custom behavior

• LoggingMiddleware for request/response logging
• TimeoutMiddleware for request timeouts
• RetryMiddleware with intelligent retry logic
• Support for custom middleware via MiddlewareInterface

✅ Fluent Request Builder - Chainable API for building requests

• Method chaining for headers, query params, body, etc.
• JSON and form data helpers
• Authentication helpers (Bearer token, Basic auth)

✅ Advanced Retry Strategies

• ExponentialBackoffStrategy with jitter support
• FixedDelayStrategy for simple retries
• RetryCondition for intelligent retry decisions
• Comprehensive retry context tracking

✅ Immutable Configuration - Thread-safe, predictable behavior

• TransportConfig for centralized configuration
• Configuration set during build phase
• No mutable setters

✅ Enhanced Exception Handling

• NetworkException for network-related errors
• TimeoutException with timeout context
• JsonParseException with detailed error info
• RetryExhaustedException with full retry history

✅ Improved Response Interface

• json() method with dot notation support
• jsonOrNull() for safe JSON parsing
• toArray() for array conversion
• Enhanced error handling

Changes

Added:

• Middleware system (MiddlewareInterface, MiddlewareStack)
• RequestBuilder for fluent API
• TransportConfig for immutable configuration
• Retry strategies (ExponentialBackoffStrategy, FixedDelayStrategy)
• RetryContext and RetryCondition
• New exception classes (NetworkException, TimeoutException, JsonParseException, RetryExhaustedException)
• Comprehensive test coverage

Modified:

• Transport and TransportBuilder refactored for middleware support
• ResponseInterface enhanced with new methods
• Response implementation with improved JSON handling
• Updated README with extensive examples

Removed:

• ClientInterface and RequestInterface (replaced by PSR interfaces directly)
• Old Request class (replaced by RequestBuilder)
• ResponseFactory (functionality moved to ResponseBuilder)
• Deprecated traits (PsrRequestTrait, PsrResponseTrait)
• Old exception classes (ClientException, MaxRetriesExceededException)

Breaking Changes

⚠️ Configuration is now immutable

• Configuration must be set during TransportBuilder build phase
• No mutable setters available after build

⚠️ Interface changes

• ClientInterface removed, uses PSR-18 directly
• RequestInterface removed, uses PSR-7 directly
• Response methods renamed (isSuccessfull() → isSuccessful())

Migration Guide

Before (v1):

$transport = new Transport();
$transport->setTimeout(30);
$response = $transport->get('https://api.example.com/users');

After (v2):

$transport = TransportBuilder::make()
    ->withBaseUri('https://api.example.com')
    ->withTimeout(30)
    ->build();
$response = $transport->get('/users')->send();

Test Plan

• All existing tests updated and passing
• New middleware tests added
• Retry strategy tests added
• Request builder tests added
• Exception handling tests added
• JSON parsing tests added
• Integration tests updated

Stats

• 41 files changed
• 2,805 insertions(+)
• 934 deletions(-)
• Net +1,871 lines

Documentation

• Comprehensive README with usage examples
• Architecture documentation
• Migration guide included
• Code examples for all major features

[codecov]

Codecov Report

❌ Patch coverage is 96.46134% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.74%. Comparing base (48a120f) to head (8834173).
⚠️ Report is 9 commits behind head on main.

Files with missing lines	Patch %	Lines
src/Factory/ClientFactory.php	50.00%	23 Missing ⚠️
src/Response.php	96.07%	2 Missing ⚠️
src/Middleware/RetryMiddleware.php	96.00%	1 Missing ⚠️
src/Transport.php	98.07%	1 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##               main      #24       +/-   ##
=============================================
+ Coverage     83.88%   96.74%   +12.86%     
- Complexity      101      270      +169     
=============================================
  Files             9       28       +19     
  Lines           242      830      +588     
=============================================
+ Hits            203      803      +600     
+ Misses           39       27       -12     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.