Requests Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require rmccue/requests
   

   No additional configuration is needed—Requests is dependency-free and works out-of-the-box.

2. First Request:

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

3. Key Properties:

   • $response->status_code (e.g., 200)
   • $response->headers (associative array of headers)
   • $response->body (response content)

First Use Case

Fetching JSON from an API:

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

Implementation Patterns

1. Session Management

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

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

$response = $session->get('/users'); // Uses session defaults

2. Handling Forms & Multipart

Form Data:

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

File Uploads:

$files = [
    'avatar' => [
        'name' => 'profile.jpg',
        'type' => 'image/jpeg',
        'tmp_name' => '/path/to/profile.jpg',
        'error' => 0,
        'size' => 1024
    ]
];
$response = Requests::post('https://api.example.com/upload', [], $files);

3. Authentication

Basic Auth:

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

Custom Auth (via \WpOrg\Requests\Auth interface):

class ApiKeyAuth implements \WpOrg\Requests\Auth {
    public function register(\WpOrg\Requests\Hooks &$hooks) {
        $hooks->register('requests.before_request', [$this, 'addHeader']);
    }
    public function addHeader(&$url, &$headers, &$data, &$type, &$options) {
        $headers['X-API-Key'] = $options['api_key'];
    }
}
$options = ['auth' => new ApiKeyAuth(), 'api_key' => 'sk_123'];

4. Error Handling

Check $response->status_code or use exceptions:

try {
    $response = Requests::get('https://api.example.com/404');
    if ($response->status_code !== 200) {
        throw new \RuntimeException("API Error: {$response->status_code}");
    }
} catch (\WpOrg\Requests\Exception $e) {
    // Handle transport errors (e.g., DNS failure)
}

5. Timeouts & Proxies

$options = [
    'timeout' => 10, // Seconds
    'proxy' => 'http://proxy.example.com:8080'
];
Requests::get('https://target.example.com', [], $options);

Gotchas and Tips

Pitfalls

1. SSL Verification:

   • Disabling verification ('verify' => false) is insecure. Use custom CA bundles instead:

     $options = ['verify' => '/path/to/cacert.pem'];
     

   • Test SSL availability first:

     use WpOrg\Requests\Capability;
     $sslAvailable = Requests::test([Capability::SSL => true]);
     

2. Redirects:

   • Follow redirects by default. Disable with:

     $options = ['follow_redirects' => false];
     

3. Headers Case Sensitivity:

   • Headers are case-insensitive in HTTP but stored as-is in $response->headers. Normalize keys if needed:

     $contentType = strtolower(array_search('application/json', $response->headers));
     

4. Multipart Files:

   • Ensure file arrays include all required keys (name, type, tmp_name, etc.). Omit error and size if not needed.

5. Session State:

   • Sessions persist across requests but do not share cookies by default. Use $session->cookies to manage them manually.

Debugging Tips

1. Inspect Raw Request/Response:

   • Enable debug output via hooks:

     \WpOrg\Requests\Hooks::register('requests.before_request', function($url, $headers, $data) {
         error_log("Request URL: $url\nHeaders: " . print_r($headers, true));
     });
     

2. Check Transport:

   • Force cURL (if available) for debugging:

     $options = ['transport' => 'curl'];
     

3. Timeout Issues:

   • Increase timeout or check server response time:

     $options = ['timeout' => 30]; // 30 seconds
     

Extension Points

1. Custom Transports:

   • Implement \WpOrg\Requests\Transport for alternative backends (e.g., Guzzle compatibility).

2. Hooks System:

   • Modify requests/responses dynamically:

     \WpOrg\Requests\Hooks::register('requests.before_request', [$this, 'modifyRequest']);
     \WpOrg\Requests\Hooks::register('requests.after_response', [$this, 'logResponse']);
     

3. PSR-18 Adapter:

   • Use art4/requests-psr18-adapter for PSR-7/PSR-18 compliance if needed.

Performance Notes

• Reuse Sessions: Avoid recreating session objects for repeated requests to the same endpoint.
• Disable Unused Features: Omit follow_redirects, decompress, or verify if not needed to reduce overhead.
• Connection Pooling: Requests does not natively support connection pooling, but sessions reuse underlying transports (cURL/fsockopen) efficiently.

Laravel-Specific Tips

1. Service Provider Binding:

   // config/app.php
   'WpOrg\Requests\Requests' => \WpOrg\Requests\Requests::class,
   
   // app/Providers/AppServiceProvider.php
   public function register() {
       $this->app->singleton(\WpOrg\Requests\Requests::class, function() {
           return new \WpOrg\Requests\Requests();
       });
   }
   

2. Facade Integration: Create a facade for cleaner syntax:

   // app/Facades/Requests.php
   namespace App\Facades;
   use Illuminate\Support\Facades\Facade;
   class Requests extends Facade {
       protected static function getFacadeAccessor() {
           return 'requests';
       }
   }
   

   Then use Requests::get() globally.

3. Exception Handling: Convert Requests exceptions to Laravel’s HttpException:

   try {
       $response = Requests::get('...');
   } catch (\WpOrg\Requests\Exception $e) {
       throw new \Symfony\Component\HttpKernel\Exception\HttpException(
           $e->getCode(),
           $e->getMessage()
       );
   }