Overseas Bundle Laravel Package

Getting Started

The Overseas Bundle simplifies HTTP client interactions in Laravel by providing a fluent, chainable API wrapper. To get started, install via Composer:

composer require answear/overseas-bundle

Publish the config (if needed) and register the service provider in config/app.php. The core feature is the Overseas facade, which allows sending HTTP requests with minimal boilerplate:

use Answear\Overseas\Facades\Overseas;

// Basic GET request
$response = Overseas::get('https://api.example.com/users');

// With query parameters
$response = Overseas::get('https://api.example.com/users', ['active' => true]);

First Use Case: Fetching and parsing JSON responses with automatic decoding:

$data = Overseas::get('https://api.example.com/data')->json();

Implementation Patterns

Core Workflow

1. Request Chaining: Build requests fluently:

   $response = Overseas::get('https://api.example.com/posts/1')
       ->withHeaders(['Authorization' => 'Bearer token'])
       ->asJson()
       ->send();
   

2. Response Handling: Use methods like json(), text(), or status():

   $status = Overseas::get('https://api.example.com/health')->status();
   

3. Error Handling: Leverage Laravel’s exception handling or use ->throw():

   try {
       $response = Overseas::post('https://api.example.com/login')->throw();
   } catch (\Answear\Overseas\Exceptions\OverseasException $e) {
       // Handle error
   }
   

Integration Tips

• Middleware: Attach middleware to all requests via config:

  'middleware' => [
      \App\Http\Middleware\AddCustomHeader::class,
  ],
  

• Macros: Extend functionality dynamically:

  Overseas::macro('authenticate', function () {
      return $this->withHeaders(['Authorization' => 'Bearer ' . auth()->token()]);
  });
  

• Testing: Use Overseas::fake() to mock responses:

  Overseas::fake([
      'https://api.example.com/users' => ['id' => 1, 'name' => 'Test'],
  ]);
  

New in 4.1.0: Response Methods

The get() method (added in PR #22) allows direct access to the underlying Guzzle response object for advanced use cases:

$guzzleResponse = Overseas::get('https://api.example.com/data')->get();
$headers = $guzzleResponse->getHeaders();

Gotchas and Tips

Pitfalls

1. Deprecated Methods: Avoid ->response() (use ->get() for raw responses or ->json()/->text() for parsed data).
2. Middleware Conflicts: Ensure custom middleware doesn’t interfere with the bundle’s default headers (e.g., Accept: application/json).
3. Rate Limiting: The bundle doesn’t enforce rate limits by default. Use Guzzle’s retry middleware or a queue system for production.

Debugging

• Enable Debugging: Set 'debug' => true in config to log requests/responses.
• Check Headers: Use ->get() to inspect raw headers if responses are malformed.
• Common Issues:
  • 401 Errors: Verify auth tokens or middleware.
  • 500 Errors: Check the raw response with ->get() for server-side clues.

Extension Points

1. Custom Adapters: Replace the default Guzzle adapter by binding your own HTTP client to the answear.overseas.adapter service provider.
2. Response Macros: Extend response handling:

   \Answear\Overseas\Overseas::macro('successful', function () {
       return $this->status() >= 200 && $this->status() < 300;
   });
   

3. Event Listeners: Listen for overseas.request and overseas.response events to log or modify requests/responses globally.

Config Quirks

• Base URL: Set 'base_url' in config to avoid repeating full URLs.
• Timeouts: Configure defaults in 'timeout' (seconds) or override per request:

  Overseas::get('...')->timeout(30);