• How to use the PECL HTTP (PECL_HTTP) Extension to make HTTP requests from PHP
• How to: PECL HTTP request exception and error handling
• PHP HttpRequest class options and notes
• How to use the file_get_contents() function to make an HTTP request from PHP

The last post mentioned above covered using the built-in file_get_contents() as an alternative if you are unable to install the HTTP PECL extension or need minimal HTTP functionality. This post will look at a third method of making HTTP requests from PHP, using the PHP Client URL Library AKA cURL library. The PHP cURL library essentially uses the cURL library from the cURL command line utility and makes the calls available via PHP functions.

Installing the PHP cURL library on Ubuntu requires just a couple simple steps:

• PHP needs to compile in the cURL library but if you are using Ubuntu you can simply execute the following shell command instead of doing a custom PHP build:

  sudo apt-get install php5-curl

• Restart Apache once the library has installed.
• Call a page with the phpinfo() function and look for a “curl” section. It should be listed there if everything installed correctly:

  

Once the cURL library is added you can call the curl functions which are documented here. The following simple example makes a call to www.example.com. You will notice that I did not “echo” the return of curl_exec() to display it. This is because by default, the curl_exec() function displays the result and returns a true on success, false on failure.

<?php
 
$curl_handle = curl_init("http://www.example.com/");
curl_exec($curl_handle);
curl_close($curl_handle);
 
?>

If you want to assign the output to a variable so you can do something with it, you will need to set the CURLOPT_RETURNTRANSFER option:

<?php
 
$curl_handle = curl_init("http://www.example.com/");
curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, true);
$results = curl_exec($curl_handle);
curl_close($curl_handle);
echo $results;
 
?>

The PHP cURL library has a variety of options you can set using the curl_setopt() function. This includes setting GET and POST requests, setting fields for each, etc.

That is the five minute version of the PHP cURL library. Another quick way to make an HTTP request is to just make a system call to the “wget” command utility which is included on most *nix systems:

<?php
 
echo system("wget -O - http://www.example.com");
 
?>

This pretty cool but I think I prefer the other methods because they all run under the Apache process. That’s it for this post!

Xdebug is a PHP extension that provides valuable debugging information such as stack traces, functions traces, profiling, code coverage analysis, etc. There is another PHP tool called DBG that has similar functionality but this post will focus on using Xdebug.

Setup Xdebug

Xdebug is a PECL module and can be installed using the PECL installation instructions in one of my previous posts.

• If you have already setup PEAR you just need to run the following from a shell:

  sudo pecl install xdebug

  If everything goes well Xdebug should download, build, and install. You may get a message telling you:

  You should add "extension=xdebug.so" to php.ini

  Go ahead and add the line. On an Ubuntu server you will probably find the php.ini file here: /etc/php5/apache2/php.ini

• Restart Apache, or whatever web server you are using, so the change will take effect.
  If you are running Apache on Ubuntu it would be:

  sudo /etc/init.d/apache2 restart

• Write a phpinfo.php page with the following code and then point a browser at it. It should show the Xdebug module there in addition to many other things:

  <?php phpinfo(); ?>

At this point the Xdebug extension should be installed. For more detailed instructions on a PECL extension install see my post: How to install a PHP PECL extension/module on Ubuntu. Note that there is a problem running the Xdebug extension with Zend Studio since it has it’s own debugger.

Enable Xdebug profiling

• By default, profiling is disable in Xdebug. Enable it by adding the following entry to the php.ini file:

  xdebug.profiler_enable=On

  On on a linux box there is often a php.d or conf.d folder that holds additional .ini file settings PHP will use. On Ubuntu the path for this folder is “/etc/php5/apache2/conf.d”. To prevent further cluttering my php.ini file with Xdebug settings, I created a xdebug.ini file to store all my Xdebug .ini file settings. This file is located in the “/etc/php5/apache2/conf.d” so it is automatically scanned when Apache is restarted.

  Now you might be tempted to enable the profiler in your script using the ini_set() function which, normally allows you to temporarily set a .ini setting for only the current script execution. Unfortunately this does not work. You must set it in the php.ini or a sub .ini file and restart the web server.

• Restart your web server (I.e. Apache) once you have “xdebug.profiler_enable” set to “On”.

By default, Xdebug will write a cachegrind.out file to the /tmp folder. It will be named something like cachegrind.out.22373 where the number at the end is the ID of the process that was profiled. If you are using Windows you will probably need to change the default folder. Also by default, this file will be overwritten by each script execution so you don’t have to worry about it getting too big. The output file behavior is highly customizable and a complete list of Xdebug settings can be found here.

Call your script and display the analysis

With Xdebug enabled, pull up the page in your browser that you want to profile. If everything is working OK a cachegrind.out file should show up in the /tmp folder.

There are a couple programs you can use to open and analyze the cachegrind file:

• WinCacheGrind (for Windows)
• KCacheGrind (for Linux)

WinCacheGrind

WinCacheGrind is not very featured but it will tell you the main thing you need to know, which is where your PHP application is spending its time. Click on the screen shot below to see the full output of my test script:

The script makes an external call to example.com using a file_get_contents() function. Based on this analysis I might try caching the call results and only make the call at some interval to keep the cache updated. This would eliminate almost 75% of the application’s overhead and is just one example of an easy-to-fix bottleneck that profiling will help identify.

KCacheGrind

KCacheGrind does essentially the same thing as WinCacheGrind but it is geared for the Linux desktop and has quite a few more bells and whistles:

KCacheGrind includes a map feature that graphically represents the percentages of where the test application spent the time:

KCacheGrind also includes a graph feature with an export option that displays a tree diagram of the linkage between all the includes and functions:

That’s it for this post. Have fun profiling!

<?php
 
echo file_get_contents("http://www.example.com");
 
?>

Someone hit that easy button.

The file_get_contents() functions as well as many other PHP file functions implement a streams abstraction layer largely conceived by Mr. Wez Furlong. This abstraction layer is what enables many of the PHP file functions to access network resources. Given this functionality “file” seems a misnomer.

The file_get_contents() function uses an HTTP GET request but what if you want to do a POST without using cURL or the PECL_HTTP extension? Furlong posted an article here on how to do just that.

This next code example uses the file_get_contents() function again but this time a few options are set first using the stream_context_create() function:

<?php
 
$http_options = stream_context_create(array(
    'http' => array(
        'user_agent' => "Mark's Browser",
        'max_redirects' => 3)));
echo file_get_contents("http://www.example.com", false, $http_options);
 
?>

Note that the array passed to the stream_context_create() function can also be used to specify a POST method, which is how Furlong does so in his blog post.

There is still yet another way to make an HTTP request from PHP that I haven’t covered yet using the PHP built-in cURL functions. I will cover these in a separate blog post.

The phpinfo() function displays just about everything you want to know about your PHP installation. It includes info on all your PECL and PEAR modules so it is a quick way to check what’s installed. It will also tell you useful web server information including any query strings you pass. To display all this good info just point your browser at a page on your server that contains the following code:

<?php
 
phpinfo();
 
?>

That’s it!

Automatic dependency checking

The phpinfo() function will give us a page that displays a lot of info. You can pass it bitwise constants to narrow down the information displayed but what if we want to check for specific items?

In my humble opinion, when developing software or anything in general, it is a good idea to design things so that the end user will not even need a manual because the user interface is obvious. When something doesn’t work, it should be equally obvious how to fix it.

If you write a PHP application that others will install and use, it is a good idea to check for dependencies when they try to use the application. This way even if they don’t read your documentation they will quickly know why the software is not working.

Using phpversion(), PHP_VERSION, and version_compare() to check the PHP verson

To get the core PHP version you can use either of the following methods:

<?php
 
echo phpversion();
echo "<br/>or<br/>";
echo PHP_VERSION;
 
?>

The above code should output something like this:

If you are using Ubunto or some other distribution, you will note that some additional stuff is tack on to the version number (I.e. “-2ubuntu4″). This makes a comparison to your expected version a little tricky but you can use a substr()/strpos() combo to get what you need. There is an easier way to do the comparison though. The version_compare() function is “PHP-standardized” version aware. So we can do something like this:

<?php
 
if (version_compare(PHP_VERSION, '5.0.0', '<')) {
    echo 'You are using PHP version ' . PHP_VERSION . 
      'This program requires PHP version 5.0.0 or higher.';
} else {
    echo 'You are using PHP 5.0.0 or higher. You are all set!';
}
 
?>

Now you can check the PHP version and notify the user if it is not the minimum required version.

The PHP function documentation for each function at www.php.net include the PHP versions that contain the function in the upper left hand corner:

You can use this to learn what versions of PHP include the functions you are using in your code to help identify your minimum PHP version requirement.

Using get_loaded_extensions() to check for extensions

The get_loaded_extensions() function will return an array of PHP extensions that you can use to check if a specific extension is installed. Use it in combination with with the in_array() function to check if the extension you require is loaded. In this example I check if the PECL_HTTP module is installed:

<?php
 
if (in_array("http",get_loaded_extensions())){
    echo 'The PECL_HTTP module is installed. '.
      'You are all set!';
} else {
    echo 'The PECL_HTTP module is not installed. '.
      'Please install it.';
}
 
?>

You can use the phpversion() function to check if extension is listed and if so, its version. This code example not only checks if the PECL_HTTP module is installed, but also checks it’s version:

<?php
 
if (!phpversion('http')){
    echo 'The PECL_HTTP module is not installed. '.
      'Please download it from '.
      '<a href="http://pecl.php.net/package/pecl_http">here</a> '.
      ' and install it.';
} else {
    if (version_compare(phpversion('http'),'1.6.0','>=')){
        echo 'The PECL_HTTP extension is installed and '.
          'version 1.6.0 or higher. You are all set!';
    } else {
        echo 'Please upgrade your PECL_HTTP extension to '.
          'version 1.6.0 or higher. You can download it '.
          '<a href="http://pecl.php.net/package/pecl_http">here'.
          '</a>.';
    }
}
 
?>

Use function_exists() to check for individual functions

So far the methods for checking dependencies have been somewhat broad. They check that the script has a certain version of PHP or extensions installed and that will likely be good enough in most cases. If you really want to be thorough you can also check if specific functions are available using the function_exists() method. In this example I check that the http_request() module, which is part of the PECL_HTTP extension, is there before I use it. If it is not, I use the less featured, built in, file_get_contents() function.

<?php
 
if (function_exists("http_get")) {
    echo 'Using the http_get():<br/>' .
        http_parse_message(http_get("http://www.example.com"))->body;
} else {
    echo 'Using the file_get_contents():<br/>' . 
        file_get_contents("http://www.example.com");
}
 
?>

Check for include files

Here is a simple way to check for include files. It doesn’t verify their content but you can at least make sure they are there:

<?php
 
if (!file_exists('httptest.php')){
    die('The httptest.php include file is missing.');
} else {
    require_once('httptest.php');
}
 
?>

Wrap up

Checking dependencies is an important part of building robust software and hopefully the above techniques will help accomplish that. Even if your end user is a very technical they will likely appreciate a good dependency checking mechanism that quickly tells them whats missing to save them time. If your software will be used by non-technical users you might want to automatically and gracefully downgrade your software feature set instead of generating errors and asking them for something they won’t know how to do. Usability is king!

The PECL_HTTP extension allows you to set a number of options when you make a request. Usually you put the options in a key=>value array and pass the array as an argument to the request functions (I.e. http_get(), http_post_data(), http_request(), etc.) or assign the array to the HttpRequest object using the setOptions() method. Here is a code example using the HttpRequest object:

In the above code the timeout was set to 10 seconds and the user agent, which is a request header that identifies the browser to the server, is set to “MyScript”. I am going to cover just a few of the options but a full list of all the request options can be found here.

timeout

The timeout option specifies the maximum amount of time in seconds that the request may take to complete. Set this too high and your HTTPD process that PHP is running in could be stalled for quite a bit waiting for a request that may never complete. If you set it too low you might have problems with sites that are just slow to respond. This may require some tweaking depending on what you are doing. If you are making requests to a web server in Taiwan you might want to set the timeout a bit higher. The default timeout does not appear to be documented in the HttpRequest options page on PHP.NET (that I could find) but if you look at the http_request_api.c file in the HTTP_PECL source code, it looks like it is 0L AKA nothing:

This indicates it will wait forever unless you explicitly set a timeout so it might be a good idea to set one! I put together a page that makes an HTTP request and then another one that will sleep for some number of seconds that I can test against.

Here is the code for the page that will sleep:

Here is the code for the page that will make the HTTP request:

<?php
$http_req = new HttpRequest("http://localhost/alongtime.php");
$http_req->setOptions(array(timeout=>10, useragent=>"MyScript"));
try {
    $http_req->send();
} catch (HttpException $ex) {
    if (isset($ex->innerException)){
        echo $ex->innerException->getMessage();
        exit;
    } else {
        echo $ex;
        exit;
    }
} //end try block
echo $http_req->getResponseBody();
?>

When I pull up the page that makes the HTTP request in my browser I get the following error:

If I don’t set the timeout option at all, the page responds 30 seconds later since it will wait forever or at least the 30 second sleep time on the target page.

connecttimeout

The connecttimeout option indicates the maximum amount of time in seconds that the request may take just connecting to the server. This does not include the time it takes for the server to process and return the data for the request. This option will have the same considerations as above although the number should be considerably lower since it is only the connection timeout and not the timeout for the whole request. Again, the default value is not documented but if you look at the http_request_api.c file in the HTTP_PECL source code, it looks like it is 3 seconds:

dns_cache_timeout

One of the interesting features of the HTTP_PECL extension is that it will cache DNS lookups. Some of the Windows operating systems do this but many of the Linux distributions do not by default. By the way, if you want to clear your cached DNS lookup entries on a Windows box use the command “ipconfig /flushdns”. If you are making multiple requests to the same site, DNS lookup caching should provide a significant performance advantage because a round trip to the DNS server isn’t required for every request. The dns_cache_timeout option sets the number of seconds that will pass before the cached DNS lookup results will expire and a new DNS lookup will be performed. Again, the default value is not documented but if you look at the http_request_api.c file in the HTTP_PECL source code, it looks like it is 60 seconds which is probably fine for most applications:

redirect

The redirect option determines how many redirects the request will follow before it returns with a response. The default is 0 (this IS documented), which may not work in many situations because some applications respond with one or two redirects for authentication, etc. If you set this too high your application may get bounced around too many times and never return. I have not tried it but you could probably put someone in a redirect loop. Anyway, a value of around 4 or 5 should be adequate for most applications I would imagine.

useragent

The useragent option allows you to specify a different User-Agent request header to send to the server than the default which is “PECL::HTTP/x.y.z (PHP/x.y.z)” where x.y.z are the versions.

I made a little one-liner test page that returns the user agent info sent to the server:

If I make an HTTP request to this page using the HttpRequest object without setting the useragent I get:

If I do something like this:

I will get:

The reason I bring this up is because some applications that you might make a request to may respond different depending on your user agent setting. In some cases you may need to spoof a specific browser to get what you are after.

Conclusion

As mentioned before, there are many more HttpRequest options. I just covered a few notable ones that I have some limited experience with.