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 LaceboxSoleHttpShoeHttp provides a fluent API:

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¶

Simple GET

$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);
}

POST JSON

$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'];
}

Multipart Form Upload

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

Basic Auth

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

SOAP Request

$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:

<?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.