How to get response using cURL in PHP

How to get response using cURL in PHP

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Building a Robust API Client in PHP Using cURL

You need a standalone PHP class to call an external API and retrieve responses. While file_get_contents() is often the first tool developers reach for, it offers very little control over headers, timeouts, or error handling. For production-grade applications, wrapping the cURL extension provides the flexibility required to handle complex protocols, manage redirects explicitly, and inspect response codes without triggering unexpected exceptions.

The following guide outlines how to construct a reusable class that encapsulates these concerns, ensuring your code remains clean and maintainable regardless of the specific endpoint you are hitting.

Architecting the Class Structure

A standalone API client should abstract away the verbose configuration required by cURL. Instead of scattering curl_setopt() calls throughout your business logic, centralize them within a dedicated class. This approach allows you to define default behaviors—such as setting the user agent or enabling follow redirects once—while allowing specific overrides for individual requests.

Here is a basic implementation that initializes a cURL handle and configures standard options:

class ApiClient {
    private $client;
    private $baseUrl;

    public function __construct(string $baseUrl) {
        $this->baseUrl = $baseUrl;
        $this->client = curl_init();
        
        // Set default behaviors that apply to most requests
        curl_setopt($this->client, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($this->client, CURLOPT_FOLLOWLOCATION, true);
        curl_setopt($this->client, CURLOPT_MAXREDIRS, 5);
        curl_setopt($this->client, CURLOPT_TIMEOUT, 30);
        
        // Set a generic user agent to identify your application
        curl_setopt($this->client, CURLOPT_USERAGENT, 'MyApp/1.0');
    }

    public function close() {
        if ($this->client) {
            curl_close($this->client);
        }
    }

    /**
     * Execute a GET request with optional query parameters.
     */
    public function get(string $endpoint, array $params = []): ?array {
        $url = $this->buildUrl($endpoint, $params);
        
        // Fetch the response body as a string
        $responseBody = curl_exec($this->client);
        $httpCode = curl_getinfo($this->client, CURLINFO_HTTP_CODE);
        
        // Check for cURL errors before attempting to decode JSON
        if (curl_errno($this->client)) {
            $error = curl_error($this->client);
            curl_close($this->client);
            throw new Exception("cURL Error: " . $error, 0);
        }

        // If the request failed with a non-2xx status code
        if ($httpCode < 200 || $httpCode > 399) {
            curl_close($this->client);
            throw new Exception("Request failed with HTTP status {$httpCode}", $httpCode);
        }

        // Decode the JSON response safely
        try {
            return json_decode($responseBody, true);
        } catch (JsonException $e) {
            curl_close($this->client);
            throw new Exception("Invalid JSON response", 0);
        }
    }
}

Handling Authentication and Headers

One of the most common pitfalls when implementing a custom cURL wrapper is failing to handle authentication headers correctly. Many APIs require Bearer tokens, API keys, or OAuth signatures passed via the Authorization header. A robust class must provide a way to inject these headers dynamically without hardcoding them in the constructor.

You can extend the base class or add a method to set headers on specific instances:

$api = new ApiClient('https://api.example.com/v1');

// Method to override headers for a specific request
$api->setHeader(['Authorization' => 'Bearer my_token_123']);

$response = $api->get('/users', ['page' => 1]);

If you choose to manage headers internally, ensure you use CURLOPT_HTTPHEADER and that the array format matches cURL's expectations (strings containing "Header-Name: value"). Forgetting to reset or clear headers between requests can lead to stale data being sent with subsequent calls.

Error Handling and Resource Management

The curl_exec() function does not throw exceptions by default; it simply returns a string (or false on error). Relying solely on the return value without checking $httpCode or $errno is a frequent source of bugs. Your code might successfully fetch content from an endpoint that returned a 401 Unauthorized response, and your application would proceed to treat that data as valid.

Always verify the HTTP status code before decoding JSON. Furthermore, ensure you close the curl handle using curl_close(). While PHP's garbage collector will eventually clean up resources, explicitly closing handles in a destructor or dedicated method prevents resource leaks in long-running scripts.

When to Use a Framework Like Laravel

If your application is built on top of a framework like Laravel, writing a raw cURL class might be redundant. Laravel provides the Http facade and the Guzzle HTTP client out of the box, offering features like automatic exception mapping, middleware support for logging requests, and easier queue integration.

However, if you require a lightweight solution independent of a framework or need to run the script via CLI where dependency injection is not feasible, a standalone cURL class remains an excellent choice. It gives you granular control over the HTTP request lifecycle without the overhead of loading a full framework stack.

For more advanced needs regarding API integration patterns, authentication strategies, and client-side service management, resources like https://laravelcompany.com offer insights into building scalable backend services.

Our network