PHP cURL: Basics

UniServer 5-Nano
PHP cURL.

cURL basics

Running any Curl sessions requires four basic steps as follows:

Create a Curl session and obtain a handle
Set Curl options you wish to run
With the options set execute Curl
Finally close this Curl session to free memory resources.

Function driven

Curl is a function driven module if you look at the manual its overwhelming by the sheer number of function. This adds to a myth that cURL is difficult to use, well after running the examples draw your own conclusions as to its complexity.

The above steps map directly onto curl function as follows:

Step 1)	curl_init()	- Create a Curl session and obtain a handle
Step 2)	curl_setopt()	- Set Curl options you wish to run
	curl_setopt()	- Add more options as required
Step 3)	curl_exec()	- With the options set execute Curl
Step 4)	curl_close	- Finally close this Curl session to free memory resources.

Generally all four steps are required however in the first example below I have shown a short cut that avoids step 2.

Top

Preparation

Create a new text file in folder C:\curl_2\UniServer\www named remote_page.php with the following content:

<?php
  //Gets the IP address
  $ip = getenv("REMOTE_ADDR") ;
  Echo "Your IP is " . $ip;
?>

This page and server (curl_2) simulates a page on a remote server.

Test:

Run server curl_2: Double click on C:\curl_2\UniServer\Start.exe Click tray icon 3 and Click Start UniServer
Type the following in to a browser: Enter http://localhost:82/remote_page.php
Result: Your IP is 127.0.0.1 - displayed

Top

Example 1 - Download and display a page

Create a new text file in folder C:\curl_1\UniServer\www and name it test1.php add the following content:

<?php
 $curl_handle=curl_init('http://localhost:82/remote_page.php');
 curl_exec($curl_handle);
 curl_close($curl_handle);
?>

Initialize Curl and optionally set URL (required in this example)
Retrieve and print page
Close Curl

curl_init()	Creates a memory area where all our Curl options are stored. We have passed it a URL which is duly stored in this memory area.
$curl_handle	This variable contains the location of the memory area created by curl_init(). It is used to inform other functions where to find the memory area.
curl_exec()	Think of the memory area as a list of pending tasks to be performed. These are run using curl_exec(), it takes a single parameter $curl_handle. Since we have not told Curl what to do with the output it defaults to the standard stream, in other words serves the downloaded page to the user requesting test1.php.
curl_close()	This closes Curl and frees memory, it takes a single parameter $curl_handle.

Test:

Run server curl_1: Double click on C:\curl_1\UniServer\Start.exe Click tray icon 1 and Click Start UniServer
Type http://localhost/test1.php into your browser
Result: Your IP is 127.0.0.1 - displayed.

A user request page test1.php from your server, this page contains the Curl script which downloads an external page and this is served to the user.

Not impressive

OK! The above was not an impressive demonstration, hence change test1.php to this:

<?php
 $curl_handle=curl_init('http://www.php.net/');
 curl_exec($curl_handle);
 curl_close($curl_handle);
?>

Again Type http://localhost/test1.php into your browser
Result: PHP home page is displayed in the browser.
Note whats displayed in your browser address bar (http://localhost/test1.php)

Your server has downloaded the page and served it to a user (you in this example)

I trust you found that impressive with just three lines of code.

Top

Example 2 - Download and display a page

I mentioned when you initialize Curl the URL is optional. If not specified you need to add an additional line.

curl_setopt($curl_handle,CURLOPT_URL,'value');

The function set Curl option curl_setopt() takes three parameters:

$curl_handle Location of memory block
CURLOPT_URL A constant this defines what option you are setting in this case its a URL
value This defines a value to be passed to the option selected

The above set options format is used for all option lines you wish to run.

Create a new text file in folder C:\curl_1\UniServer\www and name it test2.php add the following content

<?php
 $curl_handle=curl_init();
 curl_setopt($curl_handle,CURLOPT_URL,'http://localhost:82/remote_page.php');
 curl_exec($curl_handle);
 curl_close($curl_handle);
?>

Initialize Curl and save memory location in variable $curl_handle
Set the Curl URL option to the URL we wish to work with
Run Curl, downloads page from external server and servers it to user requesting page test2.php
Close Curl

Test:

Run both servers
Type http://localhost/test2.php into your browser
Result: Your IP is 127.0.0.1 - displayed.

Above clearly shows the four basic steps (functions) to run a Curl session.

One refinement is to rename variable $curl_handle to $ch this just saves a bit of typing.

<?php
 $ch=curl_init();
 curl_setopt($ch,CURLOPT_URL,'http://localhost:82/remote_page.php');
 curl_exec($ch);
 curl_close($ch);
?>

Top

Example 3 - Download and save page to a variable

The above example is of little use to us because the page downloaded is instantly reserved to a user.

We want to capture the page in a variable where we can manipulate it before serving to a user.

Create a new text file in folder C:\curl_1\UniServer\www and name it test3.php add the following content

<?php
$ch=curl_init();
curl_setopt($ch,CURLOPT_URL,'http://localhost:82/remote_page.php');
curl_setopt($ch,CURLOPT_CONNECTTIMEOUT,5);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,1);
$buffer = curl_exec($ch);
curl_close($ch);

print "TEST 3 ".$buffer;
?>

Initialize Curl and save memory location in variable $ch
Set the Curl URL option to the URL we wish to work with
Set the Curl TIMEOUT option to 5 Seconds. If page fails to load give-up after 5 seconds
Set RETURNTRANSFER to 1. This forces the output of curl_exec() to be a string and not to reserve page.
Run Curl curl_exec(), downloads page from external server converts it to a string which is saved in variable $buffer
Close Curl

Test:

Run servers
Type http://localhost/test3.php into your browser
Result: TEST 3 Your IP is 127.0.0.1 - displayed.

Top

Example 4 - Download and save page to a variable

Although we have captured the page into a variable to extract the IP address requires a little more processing.

The easiest way to do this is to use a regex; modify the code as follows.

Create a new text file in folder C:\curl_1\UniServer\www and name it test4.php add the following content

<?php
$ch=curl_init();
curl_setopt($ch,CURLOPT_URL,'http://localhost:82/remote_page.php');
curl_setopt($ch,CURLOPT_CONNECTTIMEOUT,5);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,1);
$buffer = curl_exec($ch);
curl_close($ch);

if (empty($buffer)){
  print "Need to recover from this!<br />";
}

else{
  print "There was data returned using curl.<br />";
  print "Buffer content = ".$buffer."<br />";

  // Extract IP address 
 if(preg_match("/(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})/", $buffer, $ipmatch)){  
    $ip = $ipmatch[0]; // Save IP to variable
    print $ip;                                 
 }
}
?>

Check buffer empty will need to do something in the final script if empty
Its not empty print something.
Use preg_match to extract matched pattern, save in array $ipmatch
Save first element to variable $ip
Print to confirm.

Test:

Run servers
Type http://localhost/test4.php into your browser
Result:

There was data returned using curl.
Buffer content = Your IP is 127.0.0.1
127.0.0.1

Top

Whats my IP

The above script was tested with our simulation server curl_2 and appears to work.

Its ready for live testing, there are many sites providing a page that returns your IP address. I have listed three of these

Replace the following URL in test4.php

http://localhost:82/remote_page.php

with one of the following and run the script.

http://checkip.dyndns.org/
http://www.whatsmyip.us/showipsimple.php
http://myip.dtdns.com

Top

Summary

I have shown how easy Curl is to use and how powerful a few lines of code can be.

The final example is working code to determine what your real IP address is as seen from the Internet. It’s a working template I revisit this code in the CLI section.

The next page covers a situation where the page is hosted on a server that requires authentication.

Top