PHP cURL: Basics

UNDER COSTRUCTION, PLEASE SEE THIS POST IN RESERVE COPY

UniServer 5-Nano PHP cURL.

cURL basics

Running any Curl sessions requires four basic steps as follows:

1. Create a Curl session and obtain a handle
2. Set Curl options you wish to run
3. With the options set execute Curl
4. 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: <pre> <?php

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

?> </pre> 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 <nowiki>http:</nowiki>//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:

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

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 <nowiki>http:</nowiki>//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: <pre> <?php

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

?> </pre>

• Again Type <nowiki>http:</nowiki>//localhost/test1.php into your browser
• Result: PHP home page is displayed in the browser.
• Note whats displayed in your browser address bar (<nowiki>http:</nowiki>//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. <pre> curl_setopt($curl_handle,CURLOPT_URL,'value'); </pre> 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

<pre> <?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); ?> </pre>

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 <nowiki>http:</nowiki>//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. <pre> <?php

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

?> </pre> 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

<pre> <?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; ?> </pre>

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 <nowiki>http:</nowiki>//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

<pre> <?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; } } ?> </pre>

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 <nowiki>http:</nowiki>//localhost/test4.php into your browser
• Result:

<pre> There was data returned using curl. Buffer content = Your IP is 127.0.0.1 127.0.0.1 </pre>

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

• <nowiki>http:</nowiki>//localhost:82/remote_page.php

with one of the following and run the script.

• <nowiki>http:</nowiki>//checkip.dyndns.org/
• <nowiki>http:</nowiki>//www.whatsmyip.us/showipsimple.php
• <nowiki>http:</nowiki>//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

---