Detailed Guide to Using curl_multi_add_handle in PHP: Quickly Get Started and Understand Its Working Principle

<span><span><span class="hljs-meta">&lt;?php</span></span><span>
</span><span><span class="hljs-comment">// This document is for learning and reference purposes, introducing the basic usage of the curl_multi_add_handle function in PHP.</span></span><span>
</span><span><span class="hljs-meta">?&gt;</span></span><span>
&lt;hr&gt;
<p></span># Detailed Guide to Using curl_multi_add_handle in PHP: Quickly Get Started and Understand Its Working Principle<span></p>
<p>When performing concurrent HTTP requests in PHP, <code>curl_multi_add_handle

• $multi_handle: The multi handle created via curl_multi_init().

• $ch: The single request handle created via curl_init().

The return value is a boolean indicating whether the addition was successful.

2. Why Use curl_multi Functions?

By default, each cURL request is synchronous and blocking, meaning the next request only starts after the previous one completes. This is inefficient when requesting multiple APIs or websites. The curl_multi functions provide a non-blocking concurrent processing solution.

3. Basic Example: Concurrent Requests to Multiple URLs

Here is a complete example using curl_multi_add_handle to request multiple web pages in parallel:

<span><span><span class="hljs-variable">$urls</span></span><span> = [
    </span><span><span class="hljs-string">"https://www.example.com/"</span></span><span>,
    </span><span><span class="hljs-string">"https://www.php.net/"</span></span><span>,
    </span><span><span class="hljs-string">"https://www.wikipedia.org/"</span></span><span>
];

</span><span><span class="hljs-variable">$multiHandle</span></span><span> = </span><span><span class="hljs-title function_ invoke__">curl_multi_init</span></span><span>();
</span><span><span class="hljs-variable">$curlHandles</span></span><span> = [];

// Initialize each request and add to multi handle
</span><span><span class="hljs-keyword">foreach</span> (</span><span>$urls </span><span>as </span>$url) {
    </span><span>$ch = </span><span><span class="hljs-title function_ invoke__">curl_init</span></span>();
    </span><span><span class="hljs-title function_ invoke__">curl_setopt_array</span>($ch, [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10
    ]);
    </span><span><span class="hljs-title function_ invoke__">curl_multi_add_handle</span>($multiHandle, $ch);
    </span><span>$curlHandles[] = $ch;
}

</span><span>// Execute all requests
</span><span>do {
    </span><span>$status = </span><span><span class="hljs-title function_ invoke__">curl_multi_exec</span>($multiHandle, $active);
    </span><span>if ($active) {
        </span><span><span class="hljs-title function_ invoke__">curl_multi_select</span>($multiHandle); // Wait for I/O
    }
} while ($active && $status == CURLM_OK);

</span><span>// Retrieve results
</span><span>foreach ($curlHandles as $ch) {
    </span><span>$content = </span><span><span class="hljs-title function_ invoke__">curl_multi_getcontent</span>($ch);
    </span><span>$info = </span><span><span class="hljs-title function_ invoke__">curl_getinfo</span>($ch);
    </span><span>echo "URL: " . $info['url'] . "\n";
    </span><span>echo "HTTP Code: " . $info['http_code'] . "\n";
    </span><span>echo "Content Length: " . </span><span><span class="hljs-title function_ invoke__">strlen</span>($content) . "\n\n";
    </span><span><span class="hljs-title function_ invoke__">curl_multi_remove_handle</span>($multiHandle, $ch);
    </span><span><span class="hljs-title function_ invoke__">curl_close</span>($ch);
}

</span><span><span class="hljs-title function_ invoke__">curl_multi_close</span>($multiHandle);
</span>

4. How It Works

1. Create a multi handle using curl_multi_init().

2. Create a regular cURL handle for each URL and set the options.

3. Add each handle to the multi handle using curl_multi_add_handle().

4. Start all requests with curl_multi_exec().

5. Use curl_multi_select() to block until there is activity.

6. After processing all requests, remove handles with curl_multi_remove_handle() and close all handles.

5. Common Notes

• Each handle must have all necessary CURLOPT_* options set before adding to the multi handle.

• Remember to clean up resources: curl_multi_remove_handle() and curl_close().

• curl_multi_exec() may need to be called multiple times until all operations are complete, usually within a do-while loop.

• curl_multi_select() is used to wait for network responses to avoid CPU spinning.

6. Conclusion

curl_multi_add_handle is fundamental for building high-performance network requests. Understanding its role helps you master asynchronous processing in PHP. With it, you can implement concurrent web scraping, multi-API aggregation, and other advanced features, significantly improving your PHP program's efficiency in I/O-intensive scenarios.

By practicing with examples, you will become more proficient with this function and write more efficient, professional PHP code.

<span></span>