## Getting Started

### Minimal Setup
1. **Installation**: Add Guzzle to your Laravel project via Composer:
   ```bash
   composer require guzzlehttp/guzzle

Basic Usage: Initialize the client in a service or controller:
```
use GuzzleHttp\Client;

$client = new Client();
```

First Request: Fetch data from an API endpoint:

$response = $client->get('https://api.example.com/data');
$data = json_decode($response->getBody(), true);

Key Starting Points

Laravel Service Provider: Register the client in AppServiceProvider for dependency injection:

public function register()
{
    $this->app->singleton(Client::class, function () {
        return new Client(['base_uri' => 'https://api.example.com']);
    });
}

HTTP Client Facade: Use Laravel’s HTTP client facade (which internally uses Guzzle) for simplicity:
```
use Illuminate\Support\Facades\Http;

$response = Http::get('https://api.example.com/data');
```
(Note: While Laravel’s HTTP client is preferred, understanding Guzzle’s raw capabilities is valuable for advanced use cases.)

Implementation Patterns

Common Workflows

1. API Integration

Base URI Configuration: Define a base URI in the client constructor to avoid repetition:

$client = new Client(['base_uri' => 'https://api.example.com/v1']);
$response = $client->get('/users');

Query Parameters: Pass query strings dynamically:

$response = $client->get('/users', [
    'query' => ['role' => 'admin', 'limit' => 10]
]);

Request Headers: Include headers like authentication tokens:

$response = $client->get('/users', [
    'headers' => ['Authorization' => 'Bearer ' . $token]
]);

2. Handling Responses

JSON Responses: Automatically decode JSON responses:

$response = $client->get('/users');
$users = json_decode($response->getBody(), true);

Streaming Large Responses: Use streaming for memory efficiency:

$response = $client->get('/large-file', ['stream' => true]);
$stream = $response->getBody();
while (!$stream->eof()) {
    echo $stream->read(1024);
}

3. Asynchronous Requests

Promises: Use promises for non-blocking requests:

$promise = $client->getAsync('/users');
$promise->then(function ($response) {
    echo $response->getBody();
});

Concurrent Requests: Send multiple requests in parallel:

$promises = [
    $client->getAsync('/users'),
    $client->getAsync('/posts')
];
$results = \GuzzleHttp\Promise\Utils::settle($promises)->wait();

4. Middleware for Cross-Cutting Concerns

Authentication Middleware: Add middleware to inject headers globally:

$stack = HandlerStack::create();
$stack->push(Middleware::mapRequest(function ($request) {
    return $request->withHeader('X-Custom-Header', 'value');
}));
$client = new Client(['handler' => $stack]);

Retry Logic: Implement retry middleware for transient failures:

use GuzzleHttp\Middleware;

$retryMiddleware = Middleware::retry(
    function ($retries, $request, $exception) {
        return $retries < 3 && $exception->hasResponse();
    },
    function ($retries) {
        return 100 * $retries; // Exponential backoff
    }
);
$stack->push($retryMiddleware);

5. File Uploads/Downloads

Uploading Files: Send multipart requests for file uploads:

$response = $client->post('/upload', [
    'multipart' => [
        [
            'name'     => 'file',
            'contents' => fopen('/path/to/file', 'r')
        ]
    ]
]);

Downloading Files: Save responses directly to files:

$response = $client->get('/file-to-download', [
    'sink' => 'path/to/save/file'
]);

6. Testing

Mocking Responses: Use MockHandler for unit testing:

use GuzzleHttp\Handler\MockHandler;
use GuzzleHttp\Psr7\Response;

$mock = new MockHandler([
    new Response(200, [], 'Mocked response')
]);
$handler = HandlerStack::create($mock);
$client = new Client(['handler' => $handler]);

Laravel-Specific Patterns

1. Dependency Injection

Bind Client to Container: Register the client with Laravel’s service container:

$this->app->bind(Client::class, function () {
    return new Client([
        'base_uri' => config('services.api.base_uri'),
        'timeout'  => config('services.api.timeout', 10)
    ]);
});

Inject into Controllers/Jobs:

public function __construct(private Client $client) {}

public function handle() {
    $response = $this->client->get('/data');
}

2. Config Integration

Centralized Configuration: Store API settings in config/services.php:

'api' => [
    'base_uri' => env('API_BASE_URI', 'https://api.example.com'),
    'timeout'  => env('API_TIMEOUT', 10),
    'headers'  => [
        'Accept' => 'application/json',
        'User-Agent' => 'LaravelApp/1.0'
    ]
]

Dynamic Configuration: Load config in the client constructor:
```
$client = new Client(config('services.api'));
```

3. Event Handling

Listen for HTTP Events: Use Laravel’s event system to react to HTTP responses:
```
event(new ApiResponseEvent($response));
```

Middleware Integration: Attach Laravel middleware to Guzzle requests:

$stack->push(Middleware::tap(function ($request) {
    event(new GuzzleRequestEvent($request));
}));

4. Caching Responses

Laravel Cache Integration: Cache API responses using Laravel’s cache:

$cacheKey = 'api_users_' . md5($queryString);
$users = Cache::remember($cacheKey, now()->addHours(1), function () use ($client) {
    return $client->get('/users')->json();
});

Gotchas and Tips

Common Pitfalls

1. Timeout Handling

Default Timeout: Guzzle’s default timeout is no timeout (infinite). Always set explicit timeouts:
```
$client = new Client(['timeout' => 10]); // 10 seconds
```

Connect vs. Request Timeout: Use connect_timeout and timeout separately:

$client = new Client([
    'connect_timeout' => 5,  // Time to establish connection
    'timeout'         => 10  // Time for full request/response
]);

2. SSL/TLS Issues

Certificate Verification: Disable only if absolutely necessary (e.g., testing):
```
$client = new Client(['verify' => false]); // Avoid in production!
```

Custom CA Bundle: Specify a custom CA bundle path:

$client = new Client(['verify' => '/path/to/certificate.pem']);

Self-Signed Certificates: Add self-signed certs to the trusted store or disable verification temporarily.

3. Redirects

Unlimited Redirects: Guzzle follows redirects by default, but this can lead to infinite loops:
```
$client = new Client(['allow_redirects' => false]); // Disable redirects
```

Custom Redirect Logic: Use middleware to handle redirects:

$stack->push(Middleware::redirect(function ($request) {
    return $request->getUri()->withPath('/new-path');
}));

4. Cookie Management

Cookie Jar: Share cookies across requests using a cookie jar:

$cookieJar = new CookieJar();
$client = new Client(['cookies' => $cookieJar]);

Domain-Specific Cookies: Ensure cookies are scoped to the correct domain to avoid leakage.

5. Streaming and Memory

Streaming Large Files: Always use stream => true for large responses to avoid memory issues:
```
$response = $client->get('/large-file', ['stream' => true]);
```

Guzzle Laravel Package