Author: mfoster

In a previous post, we created a simple PHP page that told us if http://www.example.com is up or down by using the PECL HTTP extension to make an HTTP request to the site and look for the string “example” in the response. Here is the code for our test page, httptest.php:

<?php

$http_req = new HttpRequest("http://www.example.com");
$http_req->setOptions(array(timeout=>10,useragent=>"MyScript"));
$http_req->send();

if (stripos($http_req->getResponseBody(), "example") === false){
    echo "The page is down!";
} else {
    echo "The page is up!";
}

?>

The problem with this code is that there is no error handling. Below are a few examples of what can go wrong and the resulting errors:

DNS Lookup Failure

If the DNS lookup fails the page will return the following error:

Since www.example.com is a valid DNS name I used “www.somewebsitethatdoesnotexist.com” instead to demonstrate what happens with an invalid name or failed DNS lookup. Note the “inner exception” that says “Couldn’t resolve host name”. More on “inner exceptions” in a bit. This is not very pretty for a diagnostic page.

Connection Failure

In this example I again used “www.somewebsitethatdoesnotexist.com” but I added the following entry to the /etc/hosts file on the server:

Now the DNS entry will resolve using the /etc/hosts file but this is not a valid IP for any machine on my neetwork so I see this error:

Again we have a inner exception buried in all of that telling me that the connection time out.

404 Error

In this example I put in “http://localhost/notarealpage.php” for the URL. This will connect to the local Apache server but that page doesn’t exist so the server will return a 404 file not found error. The server responded but since we are not checking the response code from the server our code just tells us the page is down and that is true but it would be useful to know that it is because the page is missing!

If the server responds OK we will get a 200 status code. We should handle any other response appropriately.

Handle the exceptions

The first thing we can do is put a try catch block around our code and try catching the HttpException as shown in example section of the documentation for the HttpRequest::send method:

<?php

$http_req = new HttpRequest("http://www.example.com");
$http_req->setOptions(array(timeout=>10,useragent=>"MyScript"));

try {
    $http_req->send();
} catch (HttpException $ex) {
    echo $ex->getMessage();
}

if (stripos($http_req->getResponseBody(), "example") === false){
    echo "The page is down!";
} else {
    echo "The page is up!";
}

?>

If there is a time out or connection failure the HttpException is caught and we see this:

Hmm… that is not very informative and the same error is displayed for both a name lookup failure and a connection timeout. We can also try changing:

Now we get this:

That is painfully ugly but at least get the “Couldn’t resolve host name” message in there so we know what went wrong. Still, we can do better.

In addition to putting a try-catch around the send() method you probably should surround all of your HttpRequest code with a try-catch that eventually catches “Exception” to be safe.

The undocumented inner exception

The HttpException object, which is not really documented all that well as of this writing, has something completely undocumented called an inner exception. The inner exception is a more detailed exception that is nested inside the HttpException object. We can check if an inner exception is set and if so, display that instead:

<?php

$http_req = new HttpRequest("http://www.example.com");
$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;
    }
}

if (stripos($http_req->getResponseBody(), "example") === false){
    echo "The page is down!";
} else {
    echo "The page is up!";
}

?>

Now we get just the part we are interested in:

If the lookup is OK but we get a connection timeout we now see this:

If no inner exception is detected the HttpException is echoed.

Check status codes

Sometimes the server may be responding but we do not get a 200 status. This could because of a redirect, security error, missing page, or a 500 server error. The HttpRequest object provides a getResponseCode() method so we can check what the response was and handle it appropriately. If redirects are followed the last received response is used. For this example we will simply echo out some of the common status codes if we don’t get a 200:

<?php

$http_req = new HttpRequest("http://www.example.com/blah");
$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;
    }
}

$response_code = $http_req->getResponseCode();

switch ($response_code){
    case 200:
    break;
    case 301:
    echo "301 Moved Permanently";
    exit;
    case 401:
    echo "401 Unauthorized";
    exit;
    case 404:
    echo "404 File Not Found";
    exit;
    case 500:
    echo "500 Internal Server Error";
    exit;
    default:
    echo "Did not receive a 200 response code from the server";
    exit;
}

if (stripos($http_req->getResponseBody(), "example") === false){
    echo "The page is down!";
} else {
    echo "The page is up!";
}

?>

This handles a few of the more common response/status codes. To test the code we can put in a valid URL but a bogus page (I.e. http://www.example.com/blah) If everything works right we now see the following response from our diagnostic page:

Final Notes

Our little diagnostic page can now handle most of the errors it will likely encounter when it attempts to test our example site, example.com. If we wanted to take this a bit further we could add a database back-end that maintains a list of multiple sites we would like to test. To take things a step further we could execute this PHP script from the command line via a cron job that runs every 5 minutes. We could then have the script send an e-mail when a site was down with the problem indicated in the message. If we wanted to maintain some up-times stats would could log the outages to a database and generate uptime/SLA reports daily, weekly, yearly, etc.

In reality, I would just use something like IPSentry or Nagios to conserve effort for future generations but it was nice to think about. 😉 Happy coding!

On some distributions PHP error reporting or display of errors is disabled by default as a security precaution. This is a good idea for production systems because errors may reveal useful information to undesirables. In a development environment on the other hand, it is generally useful to see your errors. 😉 If error display is disabled you may just see a blank browser window/empty page when you expect an error. To enable errors and error display, find the your php.ini file and make sure the following lines are set:

On Ubuntu you can find the php.ini file here:
/etc/php5/apache2/php.ini

On other distributions try:
/etc/php.ini

On Windows you might find it here:
c:\windows\php.ini

If you are running XAMPP it will be in the php folder off the XAMPP root.

You will need to restart Apache (or IIS as the case may be) so your changes will take effect:

On Ubuntu:

On other distributions you might try:

PECL HTTP is a feature-rich PHP extension that allows you to make HTTP and HTTPS (SSL) requests from your PHP code and handle the responses. If you are not familiar with PECL, it is a library of extensions to add functionality to PHP. It uses the same package and delivery system as PEAR.

Many distributions do not install PECL_HTTP by default even if you install PHP. If you try to use one of the PECL_HTTP object or functions (I.e. http_get()) without the extension installed you will likely get something like this:

If this error comes up but you think you installed the PECL_HTTP package and it shows up in phpinfo(), then it is possible your PECL_HTTP install failed and did not get cleaned up so phpinfo() still sees it. This may happen if you didn’t install the cURL source library dependency first (see below).

So let’s pretend we own the site http://www.example.com (See RFC 2606.) We want to build a PHP diagnostic page that will tell us that www.example.com is returning the string “example” somewhere in the page indicating if the page is up or down. First I need to install the PECL_HTTP extension. For details on how to install a PECL extension see my post “How to install a PHP PECL extension/module on Ubuntu“. For now I am going to assume that the php-pear and php5-dev packages have already been installed. These instructions are based on a Ubuntu install:

• Install the libcurl3-openssl-dev package. The HTTP_PECL extension requires some of the cURL source libraries so we will have to install the cURL library package first:
  sudo apt-get install libcurl3-openssl-dev

  If you don’t install the cURL source library package you will likely see the following error when you attempt to install the PECL_HTTP extension:

  checking for curl/curl.h... not found
  configure: error: could not find curl/curl.h
  ERROR: ‘/tmp/pear/temp/pecl_http/configure --with-http-curl-requests --with-http-zlib-compression=1 --with-http-magic-mime=no --with-http-shared-deps’ failed
• Install the HTTP_PECL module with the following command:
  sudo pecl install pecl_http

  The installer may ask you about some specific options but unless you really know what you want, you can probably just hit enter one or more times to accept all the defaults. If all goes well, the module should download, build, and install.

• Once the install is complete, it will probably ask you to add a “extension=http.so” line to your php.ini file. Open up the php.ini file in your favorite text editor and add the line under the section labeled “Dynamic Extensions”. On Ubuntu the php.ini file seems to be located in the /etc/php5/apache2 folder:
  sudo nano /etc/php5/apache2/php.ini
• Now that the php.ini file has been updated, Apache will need to be restarted so the new extension will be loaded:
  sudo /etc/init.d/apache2 restart

  That should restart Apache on Ubuntu but if that doesn’t work you can try:

  sudo /etc/init.d/httpd restart

At this point hopefully the PECL_HTTP extension is installed so now we can create a PHP script that will make an HTTP request to http://www.example.com and display the results. For this example I will use the http_get() function. The first argument is a predefined constant of the request method type (GET, POST, etc.) and the second argument is a string containing the URL. I created a file named httptest.php (using “sudo nano /var/www/httptest.php” with the following code and put it in the /var/www folder (The default HTTP root on a Ubuntu server):

or you could use the http_request function instead to do the same thing:

When the page is opened in a web browser (I.e. http://sparky/httptest.php) it returns something like this:

That’s it. Those are some pretty quick one-liners if we are fine with the default options. This time we’ll do something similar but use the HttpRequest object instead and set a timeout and a different user agent:

The output is the same as the previous two commands but this time the server could have taken up to ten seconds to respond before the request timed out. In addition, we sent the user agent string “MyScript” in the host header to the server. If you don’t want the HTTP response headers included in the the output, you use the getResponseBody() method instead:

This outputs:

No response headers this time. In fact, it looks as though you typed http://www.example.com in the browser.

I could set some URL query parameters using the setQueryData() if example.com was a dynamic page that accepts arguments but I am pretty sure it does not.

For the purpose of our example it doesn’t look like we have gotten very far but PHP is now getting a hold of the response data before we see it so we are halfway there. Now all we need to do is search for the string “example” and return some type of indicator letting us know that the example.com page is up or down:

<?php

$http_req = new HttpRequest("http://www.example.com");
$http_req->setOptions(array(timeout=>10,useragent=>"MyScript"));
$http_req->send();

/*Note: The stripos() function just returns false if it doesn't find an upper or lower case version of the string we are looking for.*/
if (!stripos($http_req->getResponseBody(), "example")){
    echo "The page is down!";
} else {
    echo "The page is up!";
}

?>

If everything is working correctly we will see:

If example.com is broken or doesn’t return the string “example” our test page returns:

This is great and all but you may have noticed there is no error handling to speak of which isn’t good. I will talk about HTTP request/PECL_HTTP error handling in a separate post but until then, happy HTTPing!

PHP PECL extensions provide additional functionality over the base PHP install. You can browse the PHP PECL extensions available at the PECL repository here. The following steps show how to install a PECL extension/module on Ubuntu using the PECL_HTTP extension as an example and assumes that you already have Apache 2 and PHP 5 installed:

• First, you will need to install PEAR via apt-get to get the necessary package and distribution system that both PEAR and PECL use. From a shell prompt enter:
  sudo apt-get install php-pear

  You will be prompted to confirm the install. Just press “y” and enter. If all goes well you should see it download and install the php-pear package.

  Note: “sudo” is used to provide the super user privileges necessary for the following command. So in this case the command “apt-get install php-pear” is being executed with super user privileges by preceding it with “sudo”. Unless configured otherwise, you will normally be prompted to enter a password when you use sudo. This is usually the same password that you logged in with.
• Now you will need to install the php5-dev package to get the necessary PHP5 source files to compile additional modules. Enter the following from a shell prompt:
  sudo apt-get install php5-dev

  If you do not install the php5-dev package and try to install a PECL extension using “pear install”, you will get the following error:

  sh: phpize: not found
  ERROR: `phpize’ failed
• The PECL_HTTP extension requires an additional dependency package to be installed. You can probably skip this for other extensions:
  sudo apt-get install libcurl3-openssl-dev
• Now we are finally ready to actually install the extension. From a shell prompt enter following but substitute “pecl_http” with the PECL extension name you are installing:
  sudo pecl install pecl_http

  The installer may ask you about some specific options for the extension you are installing. You can probably just hit enter one or more times to accept all the defaults unless you want to set specific options for your implementation. If all goes well, the module should download, build, and install.

• Once the install is complete, it will probably ask you to add a “extension=” line to your php.ini file. Open up the php.ini file in your favorite text editor and add the line under the section labeled “Dynamic Extensions”. On Ubuntu the php.ini file seems to be located in the /etc/php5/apache2 folder:
  sudo nano /etc/php5/apache2/php.ini

  In this example, the pecl_http extension install asked me to add “extension=http.so”.

• Now that the php.ini file has been updated, Apache will need to be restarted so the new extension will be loaded:
  sudo /etc/init.d/apache2 restart

  That should restart Apache on Ubuntu but if that doesn’t work you can try:

  sudo /etc/init.d/httpd restart

If all went well your PECL extension should now be working. You might want to write a PHP test page that will test the basic functionality of the extension to make sure everything is working OK. You can use this later to check that all your required extensions are installed and working when you deploy to a new server. In this example where I installed the PECL_HTTP module, I might write a PHP page that uses the extension’s HttpRequest class to go get a page and return the results.

That’s it. For the next extension install you can skip the steps to install the php-pear and php5-dev packages.