HTTP Client
===========

When your application needs to talk to other services—APIs, webhooks or microservices—you need an HTTP client. Under the hood LacePHP’s client uses PHP’s built-in cURL library, which is fast, flexible and widely supported.

Why an HTTP Client Matters
--------------------------
- **Reusability**  
  One consistent interface for GET, POST, authentication and headers.  
- **Security**  
  Automatic header handling and error checking helps you avoid common cURL pitfalls.  
- **Readability**  
  Chainable methods read like plain English: `.method('POST')->json($data)`.

cURL in a Nutshell
------------------
cURL is a PHP extension that lets you send HTTP(S) requests. You configure options (URL, method, headers, body) with `curl_setopt()`, execute with `curl_exec()`, then parse the response. LacePHP wraps all of that so you don’t have to repeat boilerplate.

Introducing `ShoeHttp`
----------------------
The class `Lacebox\Sole\Http\ShoeHttp` provides a fluent API:

.. code-block:: php

   use Lacebox\Sole\Http\ShoeHttp;

   $client = new ShoeHttp('https://api.example.com/users');
   $response = $client
       ->method('GET')
       ->header('Accept', 'application/json')
       ->send();

   // $response is an array: ['status'=>200, 'headers'=>[...], 'body'=>'...']

Key Methods
~~~~~~~~~~~
- **url(string $url)**  
  Set the request URL.  
- **method(string $verb)**  
  HTTP method (GET, POST, PUT, DELETE, OPTIONS).  
- **header(string $name, string $value)**  
  Add or overwrite a request header.  
- **authBasic($user, $pass)**, **authBearer($token)**, **authDigest($user,$pass)**  
  Common authentication schemes.  
- **formData(array $fields)**  
  Send multipart form-data (file uploads).  
- **json(mixed $data)**  
  Encode `$data` as JSON and set `Content-Type: application/json`.  
- **raw(string $data, string $contentType)**  
  Send raw text, HTML or XML.  
- **option(int $curlOpt, mixed $value)**  
  Any other cURL option you need.  
- **send()**  
  Execute the request and return `['status'=>int, 'headers'=>array, 'body'=>string]`.

Examples
--------

1. **Simple GET**

   .. code-block:: php

      $resp = (new ShoeHttp())
          ->url('https://jsonplaceholder.typicode.com/posts/1')
          ->method('GET')
          ->header('Accept','application/json')
          ->send();

      if ($resp['status'] === 200) {
          $data = json_decode($resp['body'], true);
      }

2. **POST JSON**

   .. code-block:: php

      $resp = (new ShoeHttp('https://api.example.com/login'))
          ->json(['email'=>'user@example.com','password'=>'secret'])
          ->send();

      if ($resp['status'] === 200) {
          $token = json_decode($resp['body'], true)['token'];
      }

3. **Multipart Form Upload**

   .. code-block:: php

      $resp = (new ShoeHttp('https://api.example.com/upload'))
          ->formData([
              'file' => curl_file_create('/path/to/photo.jpg'),
              'description' => 'Holiday photo'
          ])
          ->send();

4. **Basic Auth**

   .. code-block:: php

      $resp = (new ShoeHttp('https://api.example.com/secure'))
          ->authBasic('apiuser', 'apipass')
          ->send();

5. **SOAP Request**

   .. code-block:: php

      $xmlPayload = '<?xml version="1.0"?><Envelope>…</Envelope>';
      $resp = (new ShoeHttp('https://soap.example.com/endpoint'))
          ->soap('urn:MyAction')
          ->raw($xmlPayload, 'text/xml')
          ->send();

Controller Integration
----------------------
Use `ShoeHttp` inside your controller to call external APIs:

.. code-block:: php

   <?php
   namespace Weave\Controllers;

   use Lacebox\Sole\Http\ShoeHttp;
   use function kickback;

   class WeatherController
   {
       public function forecast($city)
       {
           $apiUrl = "https://api.weather.com/forecast/{$city}";
           $resp   = (new ShoeHttp($apiUrl))
               ->header('Accept','application/json')
               ->send();

           if ($resp['status'] !== 200) {
               return kickback()->serverError('Weather service unavailable');
           }

           $data = json_decode($resp['body'], true);
           return kickback()->json([
               'city'     => $city,
               'forecast' => $data['forecast'] ?? []
           ]);
       }
   }

Best Practices
--------------
- **Set timeouts** using `option(CURLOPT_TIMEOUT, 10)` to avoid hanging requests.  
- **Check status codes** before parsing the response.  
- **Reuse** a single `ShoeHttp` instance for multiple calls if the same base URL and headers apply.  
- **Escape input** for query strings with `urlencode()`.  


.. warning::

   - Always handle network errors and non-2xx status codes gracefully.  
   - Avoid sending large payloads in synchronous requests—consider background jobs.  
   - When sending user-supplied files, validate MIME types and file sizes before calling `formData()`.  

By using `ShoeHttp`, you can make secure, readable API calls without the complexity of a full HTTP library—just cURL done right.

|
|