Download the PHP package hyphun/hypcurl without Composer

HypCurl

Organised, reusable cURL toolkit for PHP 8.1+. Define each external API once as a small class, then call it from code or the terminal. Retries, timeouts, cookies, proxies, custom headers and logging are handled in one place.

• Direct use, no class needed: HypCurl::get($url)->send()->json() from any class you already have
• Ready-made template: hypcurl make:api generates HypClass, a working API class you fill in
• Singleton API clients: HypClass::instance()->items()->find(7)
• Fluent requests: $api->post('/orders')->json($data)->bearer($token)->retries(2)->send()
• REST resources with no code: list, find, create, update, patch, delete
• Cookie sessions: kept in memory, or in a cookie-jar file that persists between runs
• Global settings: set the proxy, SSL, redirects, timeouts and headers once with HypCurl::boot(['defaults' => [...]])
• Proxy support: HTTP, HTTPS and SOCKS, with credentials masked in logs
• Readable, JSON-ready errors: typed exceptions (TimeoutException, ProxyException, …) with hints, toJson(), trySend(), and uncaught errors rendered as JSON
• SSL and redirect control: verify or skip TLS checks, trust a custom CA, follow or limit redirects
• Custom headers: layered (global → per-API → per-request), and you can remove any header
• CLI: call any API method with vendor/bin/hypcurl, and see the equivalent curl command with -v
• No dependencies beyond ext-curl. Optionally logs through any PSR-3 logger.

Installation

Quick start

1. Generate your API class

Pass a name to generate more classes, one per external API: make:api Payments, make:api Sms. The namespace and folder are read from your composer.json PSR-4 autoload; with "App\\": "src/" you get App\Api\HypClass in src/Api/. You can override them with --namespace=... --path=....

2. Fill it in

The generated class works immediately: it points at httpbin.org, which echoes requests back. It has three marked sections for you to edit:

Set its URL and token in config/hypcurl/default.env / local.env. The keys use the class name as a prefix:

3. Use it in code

4. Or from the terminal

Without the generator, a class only needs to extend Hyphun\HypCurl\Api\ApiClient and implement options().

Use it directly (no extra class)

You don't have to create an API class. Call HypCurl from any class you already have.

One-off calls with a full URL:

HypCurl::get/post/put/patch/delete/request() share one client, so cookies are kept between calls, like a browser.

A configured client in your existing class. Set the base URL, auth, headers and retries once, then use the client in any method:

Each HypCurl::client() has its own settings, cookies and connection. Every request option shown below (headers, cookies, proxy, uploads, …) works the same way. See examples/direct_usage.php.

Which approach to use: direct use suits a few calls inside an existing class. An API class (make:api) is better when an API is used in many places, or when you want to call it from the terminal.

Configuration

HypCurl works without any setup. It reads HYPCURL_* environment variables and falls back to built-in defaults. To use config files, or to plug in your app's logger, call boot() once at startup:

Priority, highest first: values → environment variables → local.env → {env}.env → default.env → built-in defaults.

All keys use the HYPCURL_ prefix on purpose. Under CGI/FPM, incoming request headers become HTTP_* variables ("httpoxy"), so HTTP_* names must never be used for settings.

Logging: in the CLI, logs go to stderr. In web requests (FPM, FrankenPHP, …), HypCurl stays silent unless you pass a logger.

Global settings: set once, used everywhere

Set the proxy, TLS, redirect, timeout and header settings once at startup, so individual requests never repeat them:

These defaults apply to the HypCurl::get()/post()… shortcuts, to HypCurl::client(), and to every API class. Anything more specific still wins, in this order:

per request (->proxy(), ->insecure(), ->withoutRedirects()…) > client / API options() > defaults > *`HYPCURL_` config > built-in**

Headers are merged rather than replaced. Unknown option names throw an error, so a typo like proxyy is caught. You can also change the defaults later with HypCurl::defaults([...]). Call boot() before you create clients: a HypCurl::client() made earlier keeps its settings. Full example: examples/global_settings.php.

Requests

All of these work the same on HypCurl::get(...), on a HypCurl::client(), and inside an API class.

Responses

Errors

Every failure throws a structured exception with a readable message, a machine-readable type, and a hint on how to fix it. All of them extend HttpException:

JSON. Exceptions and responses share one envelope:

Success looks like {"success": true, "status": 200, "data": {...}}.

Without exceptions. trySend() never throws; check the result instead:

A client created with 'throw' => false behaves the same way for every request.

Uncaught errors become JSON. Add this once at startup, and an uncaught HypCurl error becomes a clean JSON response instead of Fatal error: Uncaught ... with a stack trace:

On the web it responds 502 Bad Gateway, or 504 for timeouts, with Content-Type: application/json. In the CLI it prints the JSON and exits with code 1. Other exceptions go to your existing handler unless you pass 'all' => true.

Secrets are hidden everywhere errors and logs appear: passwords in URLs, and token/api_key/password-style query parameters, are shown as ****.

Cookies: chained requests

Across separate CLI runs, use a cookie jar file:

Headers

Header names are matched case-insensitively. Values of Authorization, Cookie, X-Api-Key and similar headers are masked in logs.

Proxy

Set it globally ('defaults' => ['proxy' => ...] or HYPCURL_PROXY), per API ('proxy' => ... in options()), at runtime ($api->withProxy($url)), or per request (->proxy($url), ->withoutProxy()).

SSL / TLS

Certificates and hostnames are verified by default. Options:

Only turn verification off for local or dev servers with self-signed certificates. For internal services, prefer caBundle, which keeps verification on and trusts your company's CA.

Redirects

3xx redirects are followed by default, up to 10 hops, and only to http/https URLs: a redirect to file:// and similar is blocked.

CLI reference

The demo services httpbin and jsonplaceholder are available until you set 'examples' => false in hypcurl.php.

Long-running processes

Each API client keeps one curl handle open, so connections are reused, and frees it automatically when the process ends. You never need to call curl_close(). In workers and in FrankenPHP or RoadRunner worker mode, call HypCurl::boot() again, or MyApi::reset(), between jobs or requests. Otherwise cookies and runtime headers carry over from one user to the next.

Development

License

MIT. See LICENSE.