PHP curl_reset Function

last modified April 11, 2025

The PHP curl_reset function resets all options of a cURL session. It allows reusing the same cURL handle for multiple requests while clearing previous settings. This is useful for performance optimization.

Basic Definition

The curl_reset function resets all options set on the given cURL handle to their default values. It doesn't close the session or change the URL.

Syntax: curl_reset(CurlHandle $handle): void. The function takes a cURL handle as its only parameter. It returns nothing and throws no errors.

Basic curl_reset Usage

This example shows how to reset a cURL handle between requests.

basic_reset.php

<?php

declare(strict_types=1);

$ch = curl_init();

// First request
curl_setopt($ch, CURLOPT_URL, "https://api.example.com/data");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response1 = curl_exec($ch);

// Reset for second request
curl_reset($ch);

// Second request with different options
curl_setopt($ch, CURLOPT_URL, "https://api.example.com/users");
curl_setopt($ch, CURLOPT_POST, true);
$response2 = curl_exec($ch);

curl_close($ch);

We make two different requests using the same cURL handle. After the first request, we reset all options. This ensures no settings carry over to the second request. The handle remains open between requests.

Resetting After Error

This example demonstrates resetting a cURL handle after a failed request.

error_reset.php

<?php

declare(strict_types=1);

$ch = curl_init();

// First request with invalid URL
curl_setopt($ch, CURLOPT_URL, "https://invalid.example");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

if ($response === false) {
    echo "First request failed: " . curl_error($ch);
    curl_reset($ch); // Reset after failure
    
    // Retry with valid URL
    curl_setopt($ch, CURLOPT_URL, "https://valid.example.com");
    $response = curl_exec($ch);
    
    if ($response !== false) {
        echo "Retry succeeded";
    }
}

curl_close($ch);

After a failed request, we reset the handle before retrying. This clears any error state and previous options. The retry uses fresh settings for a clean attempt. Error handling remains intact after reset.

Reusing Handle with Different Methods

This example shows how to reuse a cURL handle for GET and POST requests.

method_reset.php

<?php

declare(strict_types=1);

$ch = curl_init();

// GET request
curl_setopt($ch, CURLOPT_URL, "https://api.example.com/data");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$getResponse = curl_exec($ch);

// Reset for POST request
curl_reset($ch);

// POST request
curl_setopt($ch, CURLOPT_URL, "https://api.example.com/data");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, ['key' =>  'value']);
$postResponse = curl_exec($ch);

curl_close($ch);

We perform a GET followed by a POST using the same handle. The reset ensures no GET options affect the POST request. Both requests have clean configurations. This pattern is efficient for multiple sequential requests.

Resetting with Custom Headers

This example demonstrates resetting a handle with custom headers.

header_reset.php

<?php

declare(strict_types=1);

$ch = curl_init();

// Request with JSON headers
curl_setopt($ch, CURLOPT_URL, "https://api.example.com/json");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Accept: application/json'
]);
$jsonResponse = curl_exec($ch);

// Reset for XML request
curl_reset($ch);

// Request with XML headers
curl_setopt($ch, CURLOPT_URL, "https://api.example.com/xml");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/xml',
    'Accept: application/xml'
]);
$xmlResponse = curl_exec($ch);

curl_close($ch);

We make requests with different content type headers. The reset clears all previous headers. Each request gets its own specific headers without interference. This is useful for APIs requiring different content types.

Performance Comparison

This example compares handle reuse with and without reset.

performance.php

<?php

declare(strict_types=1);

// Without reset (recreating handle)
$start = microtime(true);
for ($i = 0; $i < 100; $i++) {
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "https://api.example.com/test");
    curl_exec($ch);
    curl_close($ch);
}
$time1 = microtime(true) - $start;

// With reset (reusing handle)
$start = microtime(true);
$ch = curl_init();
for ($i = 0; $i < 100; $i++) {
    curl_reset($ch);
    curl_setopt($ch, CURLOPT_URL, "https://api.example.com/test");
    curl_exec($ch);
}
curl_close($ch);
$time2 = microtime(true) - $start;

echo "Without reset: $time1 seconds\n";
echo "With reset: $time2 seconds\n";

This benchmark shows the performance benefit of reusing handles. The reset version avoids repeated initialization. Handle reuse with reset is typically faster for multiple requests. The difference grows with more requests.

Best Practices

Reuse Handles: Reset instead of recreating for performance.
Clear State: Reset between different request types.
Error Recovery: Reset after failures before retrying.
Memory: Still close handles when done with curl_close.
Testing: Verify reset behavior with complex options.

Source

PHP curl_reset Documentation

This tutorial covered the PHP curl_reset function with practical examples showing its usage for efficient cURL handle management.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all PHP cURL tutorials.

Ebooks