Getting Started

Minimal Setup

Installation:
```
composer require mashape/unirest-php
```
Add to composer.json under require (not require-dev):
```
"require": {
    "mashape/unirest-php": "^3.0"
}
```
Include autoloader (Laravel handles this automatically via Composer).

First Request:

use Unirest\Request;

$response = Request::get('https://api.example.com/data');
$data = $response->body; // Parsed JSON/response

Key Use Case: Fetch JSON data from an API with automatic parsing:

$response = Request::get('https://api.github.com/users/octocat');
$user = $response->body; // Directly usable as PHP object/array

Implementation Patterns

Common Workflows

1. API Client Wrapper

Create a service class to abstract API calls:

class GitHubApi {
    public function getUser($username) {
        $response = Request::get("https://api.github.com/users/{$username}");
        return $response->body;
    }
}

2. Request/Response Handling

Use middleware-like logic for responses:

$response = Request::post('https://api.example.com/login', [
    'Accept' => 'application/json',
], ['email' => 'user@example.com', 'password' => 'secret']);

if ($response->code !== 200) {
    throw new \RuntimeException('Login failed: ' . $response->raw_body);
}

3. File Uploads

Handle multipart uploads (e.g., for image APIs):

$body = Request\Body::multipart([
    'title' => 'My File',
], [
    'file' => Request\Body::file('/path/to/file.jpg', 'image/jpeg', 'filename.jpg')
]);

$response = Request::post('https://api.example.com/upload', [], $body);

4. Authentication

Reuse auth across requests:

Request::auth('api_username', 'api_password');
$response = Request::get('https://secure-api.example.com/data');

5. Pagination

Loop through paginated results:

$page = 1;
do {
    $response = Request::get("https://api.example.com/data?page={$page}");
    $data = $response->body;
    // Process $data
    $page = $data->next_page ?? null;
} while ($page);

Integration Tips

Laravel-Specific Patterns

Service Providers: Bind the client to Laravel’s container:

$this->app->singleton('github', function () {
    return new GitHubApi();
});

HTTP Client Facade: Extend Laravel’s Http facade for consistency:

// In a service provider
app()->singleton('unirest', function () {
    return new class {
        public function get($url) {
            return Request::get($url)->body;
        }
    };
});

Exception Handling: Convert Unirest responses to Laravel exceptions:

try {
    $response = Request::get('https://api.example.com/fail');
    return $response->body;
} catch (\Exception $e) {
    throw new \App\Exceptions\ApiException($response->raw_body, $response->code);
}

Performance

Reuse Connections: Set default headers globally:

Request::setDefaultHeader('Authorization', 'Bearer ' . config('services.api.token'));

Timeouts: Avoid hanging requests:
```
Request::timeout(10); // 10 seconds
```

Gotchas and Tips

Pitfalls

Deprecated Methods: Avoid Request::get(..., null, null, 'user', 'pass') (Basic Auth). Use Request::auth() instead.

JSON Parsing:

Requires PHP’s json extension. Test with:

if (!extension_loaded('json')) {
    throw new \RuntimeException('JSON extension is required.');
}

Custom flags may break parsing. Default to JSON_OBJECT_AS_ARRAY for consistency:
```
Request::jsonOpts(true, 512, JSON_OBJECT_AS_ARRAY);
```

File Uploads:
- Paths must be absolute or relative to the script’s working directory.
- Large files may hit PHP’s post_max_size or upload_max_filesize. Adjust in php.ini or use chunked uploads.

Proxy Issues:

Ensure proxy credentials are correct. Test with:

Request::proxy('proxy.example.com', 8080);
Request::proxyAuth('proxy_user', 'proxy_pass');

Response Handling:
- raw_body contains the exact response (including errors). Use for debugging:
```
if ($response->code >= 400) {
    logger()->error($response->raw_body);
}
```

Debugging

Enable cURL Verbose:
```
Request::verbose(); // Logs cURL debug info to stderr
```
Check Laravel logs (storage/logs/laravel.log) for details.

Inspect Headers:

$response = Request::get('https://api.example.com/data');
logger()->debug('Response Headers:', $response->headers);

Timeout Errors:
- Increase timeout or check network connectivity:
```
Request::timeout(30); // 30 seconds
```

Extension Points

Custom Response Parsers: Override default parsing (e.g., for XML):

$response = Request::get('https://api.example.com/data');
$body = simplexml_load_string($response->raw_body);

Middleware: Add pre/post-request logic:

Request::before(function ($request) {
    $request->setHeader('X-Custom-Header', 'value');
});

Mocking for Tests: Use Mockery or Laravel’s Http mocks:

$mock = Mockery::mock('overload:Unirest\Request');
$mock->shouldReceive('get')->andReturn((object) [
    'code' => 200,
    'body' => ['key' => 'value'],
]);

Configuration Quirks

Default Headers: Set globally once (e.g., in AppServiceProvider):

Request::setDefaultHeader('User-Agent', 'MyApp/1.0');
Request::setDefaultHeader('Accept', 'application/json');

Cookie Persistence: Use a temporary file for session cookies:

$cookieFile = storage_path('app/unirest_cookies.txt');
Request::cookieFile($cookieFile);

Gzip Compression: Enable automatically (default) or disable:
```
Request::setOption(CURLOPT_ENCODING, ''); // Disable gzip
```

Laravel-Specific Tips

Cache Responses: Use Laravel’s cache with Unirest:

$cacheKey = "api_data_{$timestamp}";
if (!$data = cache()->get($cacheKey)) {
    $response = Request::get('https://api.example.com/data');
    $data = $response->body;
    cache()->put($cacheKey, $data, now()->addHours(1));
}

Queue Long Requests: Offload heavy requests to queues:
```
dispatch(new ProcessApiData($url))->onQueue('api');
```

Rate Limiting: Implement exponential backoff:

$attempts = 0;
$maxAttempts = 3;
$delay = 1000; // ms

while ($attempts < $maxAttempts) {
    try {
        $response = Request::get('https://api.example.com/rate-limited');
        break;
    } catch (\Exception $e) {
        if ($attempts === $maxAttempts - 1) throw $e;
        usleep($delay);
        $delay *= 2;
        $attempts++;
    }
}

Unirest Php Laravel Package