PHP code example of hyphun / hypcurl

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

hyphun / hypcurl example snippets

namespace App\Api;

final class HypClass extends ApiClient
{
    // 1. CONNECTION: base URL, auth, default headers, timeouts
    protected function options(): array
    {
        $config = Config::instance();

        return [
            'baseUrl' => $config->get('HYP_CLASS_BASE_URL', 'https://httpbin.org'),
            'headers' => array_filter([
                'Accept' => 'application/json',
                'Authorization' => ($token = $config->get('HYP_CLASS_TOKEN')) ? "Bearer $token" : null,
            ]),
            'retries' => 2,
        ];
    }

    // 2. RESOURCES: REST collections get list/find/create/update/patch/delete for free
    public function items(): CrudResource
    {
        return $this->resource(CrudResource::class, '/items');
    }

    // 3. YOUR ENDPOINTS: one method per call; copy a pattern and edit it
    public function search(string $query, array $filters = []): Response
    {
        return $this->get('/search')->query(['q' => $query] + $filters)->send();
    }

    public function createOrder(array $order): Response
    {
        return $this->post('/orders')->json($order)->send();
    }

    // ... also 

use App\Api\HypClass;

$api = HypClass::instance();               // same instance everywhere

$results = $api->search('php', ['page' => 2])->json('data');
$order   = $api->createOrder(['item' => 'pen', 'qty' => 2])->json('id');
$item    = $api->items()->find(7)->json();

use Hyphun\HypCurl\HypCurl;

$users = HypCurl::get('https://api.example.com/users')->query(['page' => 2])->send()->json();

$order = HypCurl::post('https://api.example.com/orders')
    ->json(['item' => 'pen', 'qty' => 2])
    ->bearer($token)
    ->send();

$id = $order->json('id');

use Hyphun\HypCurl\Http\HttpClient;
use Hyphun\HypCurl\Http\HttpException;
use Hyphun\HypCurl\HypCurl;

class OrderService
{
    private HttpClient $shop;

    public function __construct()
    {
        $this->shop = HypCurl::client([
            'baseUrl' => 'https://shop.example.com/api',
            'headers' => ['X-Api-Key' => getenv('SHOP_API_KEY')],
            'retries' => 2,
            'timeout' => 15,
        ]);
    }

    public function find(int $id): ?array
    {
        try {
            return $this->shop->get("/orders/$id")->send()->json();
        } catch (HttpException $e) {
            if ($e->response?->status === 404) {
                return null;
            }
            throw $e;
        }
    }

    public function create(array $order): int
    {
        return $this->shop->post('/orders')->json($order)->send()->json('id');
    }
}

use Hyphun\HypCurl\HypCurl;

HypCurl::boot([
    'config_dir' => __DIR__ . '/config/hypcurl',   // default.env, {env}.env, local.env
    'env'        => 'prod',                        // default: HYPCURL_ENV, APP_ENV, or "dev"
    'values'     => ['HYPCURL_TIMEOUT' => 15],     // highest priority
    'base_path'  => __DIR__,                       // for relative paths (cookie jar); default: cwd
    'logger'     => $monolog,                      // any PSR-3 logger
]);

use Hyphun\HypCurl\HypCurl;

// e.g. in index.php, a service provider, or your app's bootstrap
HypCurl::boot([
    'defaults' => [
        'proxy'           => 'http://user:[email protected]:3128',
        'noProxy'         => 'localhost,.internal',
        'verifySsl'       => true,
        'caBundle'        => __DIR__ . '/certs/company-ca.pem',
        'followRedirects' => true,
        'maxRedirects'    => 5,
        'timeout'         => 20,
        'connectTimeout'  => 5,
        'retries'         => 2,
        'headers'         => ['X-App' => 'my-app'],
    ],
]);

HypCurl::get('https://api.example.com/users')->send();   // uses all of the above

$res = $api->post('/orders')
    ->query(['draft' => true])                 // ?draft=true
    ->json(['item' => 'pen', 'qty' => 2])      // or ->form([...]), ->body($raw, 'text/xml')
    ->multipart(['file' => '@/path/photo.png'])
    ->header('X-Request-Id', 'r-1')
    ->headers(['X-A' => '1', 'X-B: 2'])
    ->withoutHeader('User-Agent')
    ->bearer($token)                           // or ->basicAuth($user, $pass)
    ->cookie('session', $sid)
    ->proxy('http://127.0.0.1:8080')           // or ->withoutProxy()
    ->insecure()                               // skip TLS check; or ->verifySsl(true)
    ->followRedirects(true, 3)                 // or ->withoutRedirects()
    ->timeout(10)
    ->retries(3)
    ->saveTo('/tmp/file.pdf')                  // stream large downloads to disk
    ->send();

$res->status;              // 200
$res->ok();                // 2xx
$res->json();              // decoded body
$res->json('data.0.id');   // dot path
$res->header('content-type');
$res->cookie('session');   // cookie set by this response
$res->body;  $res->time;  $res->url;
$res->finalUrl;            // URL after redirects
$res->redirects;           // how many redirects were followed
$res->redirectUrl;         // Location of a 3xx that was NOT followed
$res->isRedirect();        // 3xx (only when not following)
$res->toArray();           // JSON-ready envelope (see Errors)
$res->toJson();

use Hyphun\HypCurl\Http\{HttpException, ClientException, TimeoutException, ProxyException};

try {
    $user = $api->get('/users/7')->send()->json();
} catch (ClientException $e) {
    if ($e->type === 'not_found') { /* ... */ }
} catch (TimeoutException | ProxyException $e) {
    // ...
} catch (HttpException $e) {         // everything else
    $e->type;        // 'server_error', 'dns_error', ...
    $e->reason;      // "503 Service Unavailable: Maintenance" (short, no URL)
    $e->getMessage();// reason + (METHOD url)
    $e->hint;        // what to check
    $e->status();    // HTTP status, or null if no response
    $e->response;    // Response for 4xx/5xx
    $e->retryable(); // temporary problem?
}

$e->toArray();                // full details: hint, request, curl code, upstream body (logs, development)
$e->toArray(debug: false);    // only type, message, status: safe to return to end users
$e->toJson();  json_encode($e);

$res = $api->get('/users')->trySend();

if ($res->ok()) {
    return $res->json();
}
$res->error->type;                     // the exception, if you need it
return $res->toArray(debug: false);    // or pass the error straight through as JSON

HypCurl::boot(['json_errors' => true]);                // production: type + message only
HypCurl::boot(['json_errors' => ['debug' => true]]);   // development: + hint, URL, curl, upstream body
// or HypCurl::jsonErrors(debug: false, allExceptions: false);

$api->post('/login')->form(['user' => $u, 'pass' => $p])->send();  // server sets a session cookie
$api->get('/dashboard')->send();                                    // the cookie is sent automatically

$api->sessionCookies();   // inspect
$api->clearCookies();     // reset

$res = HypCurl::get('https://example.com/short-link')->withoutRedirects()->send();
$res->status;        // 301
$res->redirectUrl;   // where it points

bash
vendor/bin/hypcurl init        # once: creates hypcurl.php + config/hypcurl/
vendor/bin/hypcurl make:api    # creates src/Api/HypClass.php and registers it

bash
composer install
composer test        # PHPUnit; spins up a local server, no internet needed
php examples/direct_usage.php
php examples/global_settings.php
php examples/error_handling.php
php examples/demo_flow.php
php examples/cookie_flow.php