cURL is one of the most powerful PHP extensions. It stands for Client URL, and allows you to
communicate with other servers using a wide range of protocols. Perhaps
that sounds fairly uninteresting, but give it some more thought. Other
servers and other protocols? At some stage in a novice developer’s career, there comes a time to break out of the local server, and cURL is the first thing you should consider. I first used cURL for quite a simple task – processing a file on an FTP server. Later for dealing with merchant
payments to create a transparent way of handling credit card
authentication. And later still as a convenient way to get data from
Amazon.com. The possibilities are almost limitless. I haven’t even scratched
the surface of what cURL can do, but for certain it’s a powerful library.
communicate with other servers using a wide range of protocols. Perhaps
that sounds fairly uninteresting, but give it some more thought. Other
servers and other protocols? At some stage in a novice developer’s career, there comes a time to break out of the local server, and cURL is the first thing you should consider. I first used cURL for quite a simple task – processing a file on an FTP server. Later for dealing with merchant
payments to create a transparent way of handling credit card
authentication. And later still as a convenient way to get data from
Amazon.com. The possibilities are almost limitless. I haven’t even scratched
the surface of what cURL can do, but for certain it’s a powerful library.
libcurl (the library behind the PHP cURL extension) currently supports a wide range of protocols, including HTTP, HTTPS, FTP, TELNET, FILE, LDAP, DICT, GOPHER and HTTPS, as well as HTTPS certificates, HTTP
POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies, cookies, and user:password
authentication. There are alternatives for some of these, such as
streams, sockets or the FTP extension, but cURL is the master of them all – they are less flexible, and don’t perform as well.
POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies, cookies, and user:password
authentication. There are alternatives for some of these, such as
streams, sockets or the FTP extension, but cURL is the master of them all – they are less flexible, and don’t perform as well.
Unfortunately cURL does not come with PHP by default. This tutorial assumes you know how to install extensions (or even better, know someone who does). PHP needs at least CURL 7.0.2-beta or higher, PHP 4.2.3, requires at least CURL 7.9.0 or higher, PHP 4.3.0 needs CURL 7.9.8 or higher and PHP 5.0.0 needs at least version 7.10.5 or greater. The PHP/cURL page will have details for more recent versions of PHP. You can read the PHP manual for more about installing Windows extensions, and extensions in a Unix environment.
A first cURL script
Let’s dive right in with a simple script.
<?php
//curl1.php
// initialise the cURL session, passing an optional URL
$ch = curl_init('http://www.example.co.za/recipient.php');
//Execute the session
curl_exec($ch);
//Close the cURL session
curl_close($ch);
?>
The recipient script is:
<?php
// recipient.php
print "Greetings, visitor from {$_SERVER['REMOTE_ADDR']}";
?>
The curl1.php script connects to the URL supplied (recipient.php), handing over control to
that script. Not particularly useful, but it introduces you to three of
the main functions: curl_init(), which returns a cURL handle (hence the
results are usually assigned to a variable called $ch), curl_exec(),
which executes the session you’ve set up, and curl_close(), which frees
all resources associated with the session. curl_exec() returns a
boolean in the above context, but most often you will ask it to return
the output from the call, which we look at later.
that script. Not particularly useful, but it introduces you to three of
the main functions: curl_init(), which returns a cURL handle (hence the
results are usually assigned to a variable called $ch), curl_exec(),
which executes the session you’ve set up, and curl_close(), which frees
all resources associated with the session. curl_exec() returns a
boolean in the above context, but most often you will ask it to return
the output from the call, which we look at later.
A simple cURL script to look up the meaning of a word
Let’s look at a more practical use. One of the protocols cURL supports
is dict. In this example, we’ll create a simple tool to return the
definition of a word from dict.org’s database, connecting to dict.org with the dict protocol. Using something similar you can create an
online dictionary, or integrate a word search into other applications. This
article is not about using forms to submit values to a PHP script – I
assume you already know how to do that, and can build upon this
skeleton, taking proper care to validate all variables.
is dict. In this example, we’ll create a simple tool to return the
definition of a word from dict.org’s database, connecting to dict.org with the dict protocol. Using something similar you can create an
online dictionary, or integrate a word search into other applications. This
article is not about using forms to submit values to a PHP script – I
assume you already know how to do that, and can build upon this
skeleton, taking proper care to validate all variables.
<html>
<body>
<form action="curl2.php" method="POST">
Please enter a word:
<input type="text" name="word">
<input type="submit">
</form>
</body>
</html>
<?php
// curl2.php
//get the word submitted from the form
$word = addslashes($_POST['word']);
// validate the word
if ($word != '') {
// initialise the session, this time with no URL
$ch = curl_init();
// Set the URL, which includes $word, and is of the dict protocol
curl_setopt($ch, CURLOPT_URL, "dict://dict.org/d:($word)");
// Return the output from the cURL session rather than displaying in the browser.
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
//Execute the session, returning the results to $definition, and close.
$definition = curl_exec($ch);
curl_close($ch);
//display the results - I'll leave the formatting to you
print "Definition of $x: $definition";
}
?>
The new function introduced here is curl_setopt(). This takes a cURL
handle, an option and a value for this option as arguments. $ch is of
course the handle, while we introduce two of the options, CURLOPT_URL
and CURLOPT_RETURNTRANSFER. CURLOPT_URL takes the URL for the script to
fetch, and can also be set by passing the argument to curl_init(), as
we did in the previous example. CURLOPT_RETURNTRANSFER is also one
you’ll probably be using most of the time – setting it to true returns
the results as a string for processing in your script, rather than just simply displaying it, as in
the previous example.
handle, an option and a value for this option as arguments. $ch is of
course the handle, while we introduce two of the options, CURLOPT_URL
and CURLOPT_RETURNTRANSFER. CURLOPT_URL takes the URL for the script to
fetch, and can also be set by passing the argument to curl_init(), as
we did in the previous example. CURLOPT_RETURNTRANSFER is also one
you’ll probably be using most of the time – setting it to true returns
the results as a string for processing in your script, rather than just simply displaying it, as in
the previous example.
