Requests Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require rmccue/requests
   

   Ensure autoload.php is included (Composer handles this automatically).

2. First Request:

   use WpOrg\Requests\Requests;
   
   $response = Requests::get('https://api.github.com/events');
   echo $response->body; // Raw response body
   

3. Key Properties:

   • $response->status_code (e.g., 200)
   • $response->headers (associative array)
   • $response->body (raw response content)
   • $response->success (boolean for HTTP 2xx/3xx)

First Use Case: API Integration

Fetch JSON data from an API and decode it:

$response = Requests::get('https://api.example.com/data', [
    'Accept' => 'application/json'
]);
$data = json_decode($response->body, true);

Implementation Patterns

1. Session-Based Workflows

Reuse defaults (headers, auth, base URL) across multiple requests:

$session = new \WpOrg\Requests\Session('https://api.example.com');
$session->headers['Authorization'] = 'Bearer token123';
$session->useragent = 'MyApp/1.0';

$response = $session->get('/users'); // Automatically prepends base URL

2. Handling Different HTTP Methods

• GET/POST/PUT/DELETE/PATCH:

  $response = Requests::post('https://api.example.com/users', [], [
      'name' => 'John Doe',
      'email' => 'john@example.com'
  ]);
  

• Form Data vs. JSON:

  // Form data (URL-encoded)
  Requests::post('url', [], ['key' => 'value']);
  
  // JSON payload
  Requests::post('url', ['Content-Type' => 'application/json'], json_encode(['key' => 'value']));
  

3. Authentication

• Basic Auth:

  $response = Requests::get('https://api.example.com/protected', [], [
      'auth' => ['username', 'password']
  ]);
  

• Bearer Tokens:

  $response = Requests::get('https://api.example.com/protected', [
      'Authorization' => 'Bearer token123'
  ]);
  

4. Error Handling

Check for failures and handle errors gracefully:

$response = Requests::get('https://api.example.com/data');
if (!$response->success) {
    throw new \RuntimeException("API request failed: {$response->status_code}");
}

5. File Uploads

Multipart form data for file uploads:

$files = [
    'file' => [
        'name' => 'example.txt',
        'content' => file_get_contents('example.txt'),
        'filename' => 'example.txt',
        'type' => 'text/plain'
    ]
];
Requests::post('https://api.example.com/upload', [], $files);

6. Integration with Laravel

Wrap Requests in a Laravel service provider or facade:

// app/Providers/AppServiceProvider.php
public function boot()
{
    $this->app->singleton('requests', function () {
        return new \WpOrg\Requests\Requests();
    });
}

Use in controllers:

use Illuminate\Support\Facades\Facade;

class ApiController extends Controller
{
    public function fetchData()
    {
        $response = app('requests')->get('https://api.example.com/data');
        return response()->json(json_decode($response->body, true));
    }
}

Gotchas and Tips

1. SSL Verification Pitfalls

• Default Behavior: Requests uses the system CA bundle if verify is true or omitted.
  • Risk: Outdated CA bundles may fail to verify modern certificates.
  • Fix: Explicitly set verify => true or provide a custom CA path:

    $response = Requests::get('https://api.example.com', [], [
        'verify' => '/path/to/custom/cacert.pem'
    ]);
    

• Disable Verification (Not Recommended):

  $response = Requests::get('https://insecure.example.com', [], [
      'verify' => false
  ]);
  

2. Content-Type Ambiguity

• Issue: Omitting Content-Type may lead to inconsistent behavior (e.g., multipart/form-data vs. application/x-www-form-urlencoded).
• Fix: Always specify Content-Type explicitly:

  // For JSON
  Requests::post('url', ['Content-Type' => 'application/json'], json_encode($data));
  
  // For form data
  Requests::post('url', ['Content-Type' => 'application/x-www-form-urlencoded'], http_build_query($data));
  

3. Session vs. Static Requests

• Gotcha: Sessions share state (e.g., cookies) across requests. Useful for APIs requiring session persistence but can cause unexpected behavior if misused.
• Tip: Reset sessions when needed:

  $session->reset();
  

4. Timeout Handling

• Default: No timeout (infinite wait).
• Fix: Set timeouts explicitly:

  $response = Requests::get('https://slow.example.com', [], [
      'timeout' => 10 // 10 seconds
  ]);
  

5. Debugging Responses

• Inspect Headers: Use var_dump($response->headers) to debug HTTP issues.
• Raw Body: For binary data (e.g., images), access $response->body directly.
• Error Codes: Check $response->status_code and $response->error for failures.

6. Performance Considerations

• Reuse Connections: Sessions reuse underlying connections (cURL/fsockopen), reducing overhead for multiple requests.
• Disable Cookies: If not needed, disable cookie handling to avoid unnecessary headers:

  $session->options['cookies'] = false;
  

7. Extension Points

• Custom Transports: Override WpOrg\Requests\Transport\TransportInterface for specialized needs (e.g., proxy support).
• Response Parsing: Extend WpOrg\Requests\Response to add custom methods (e.g., JSON decoding):

  class ExtendedResponse extends \WpOrg\Requests\Response {
      public function json() {
          return json_decode($this->body, true);
      }
  }
  

8. Laravel-Specific Tips

• Service Container: Bind Requests to Laravel’s container for dependency injection:

  $this->app->bind('requests', function () {
      return new \WpOrg\Requests\Requests();
  });
  

• Middleware: Create middleware to add headers/auth to all requests:

  class ApiAuthMiddleware {
      public function handle($request, Closure $next) {
          $requests = app('requests');
          $requests->headers['Authorization'] = 'Bearer ' . auth()->token();
          return $next($request);
      }
  }
  

9. Common Errors and Fixes

10. Testing

• Mock Responses: Use PHP’s stream_context_create to mock HTTP responses in tests:

  $context = stream_context_create([
      'http' => [
          'method' => 'GET',
          'header' => "Content-Type: application/json\r\n",
          'content' => json_encode(['test' => 'data'])
      ]
  ]);
  $response = Requests::get('http://example.com', [], [], $context);