Using cURL to Call External APIs

PHP cURL creates an HTTP transfer, sets transport options and separates network failures from HTTP status.

What It Does

PHP cURL creates an HTTP transfer, sets transport options and separates network failures from HTTP status. The following examples distinguish a normal use case, a boundary case and a practical application.

Requirements and Compatibility

PHP 8.x and a local test environment. Apply input validation, correct error handling and the requirements of any optional libraries.

The code focuses on the core concept. Production implementation may also need routes, validation, persistence, authorization or deployment tooling.

Example 1: Basic Behavior

Make a bounded HTTPS GET and separately check cURL failure, HTTP status and JSON schema.

<?php
$ch = curl_init('https://api.example.test/v1/products');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 3,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_HTTPHEADER => ['Accept: application/json'],
]);
$body = curl_exec($ch);
if ($body === false) throw new RuntimeException('Transport error: ' . curl_errno($ch));
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status !== 200) throw new RuntimeException('Upstream status ' . $status);
$items = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!is_array($items)) throw new UnexpectedValueException('Bad response shape');
print_r($items);

This example depends on an installed extension, third-party library or configured service and is not a standalone local test.

Example 2: Another Case

Send an explicitly JSON-encoded POST to a predetermined HTTPS endpoint.

<?php
$payload = json_encode(['name' => 'Notebook'], JSON_THROW_ON_ERROR);
$ch = curl_init('https://api.example.test/v1/products');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_POSTFIELDS => $payload,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10, CURLOPT_FOLLOWLOCATION => false]);
$response = curl_exec($ch);
if ($response === false) throw new RuntimeException(curl_error($ch));
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

This example depends on an installed extension, third-party library or configured service and is not a standalone local test.

Practical Example: Putting It to Use

Handle provider rate limits without assuming an HTTP response is a transport error.

<?php
$status = 429; $retryAfter = 15;
if ($status === 429) echo "Wait at least " . min($retryAfter, 60) . " seconds";

Important Behavior and Edge Cases

Configure connect/total timeouts, TLS verification, redirect policy and allowed outbound destinations.

Comparison with Related Functions or Approaches

Common Beginner Mistakes

Key Takeaways

• PHP cURL creates an HTTP transfer, sets transport options and separates network failures from HTTP status.
• Configure connect/total timeouts, TLS verification, redirect policy and allowed outbound destinations.
• Guzzle or Symfony HttpClient can provide higher-level request and response abstractions.

Before adapting these examples, verify the return values, test the failure paths and confirm that your application meets its security and environment requirements.