PHP Pinger
Documentation

Summary

• Include library
• Create a new instance
• Add host to be checked
• Run the ping
• Register a callback function
• Register pre/post run callbacks
• Notifications
  • Notifications levels
  • Set destinators to notify
  • Enable notifications
  • Disable notifications
  • Personalize the subject's preffix
  • Add an e-mail signature
• TL;DR

Include library

require 'phppinger.class.php';

Create a new instance

$ping = new PHP_Pinger();

Add host to be checked

The easy way:

$ping->addHost('nicolabricot.com');

You can also specified a port (default port is 80):

$ping->addHost('nicolabricot.com', 80);

You can optionnaly add a sweety name (default label is the hostname):

$ping->addHost('nicolabricot.com', 80, 'My blog');

PHP Pinger use a socket to check if the host is online. It opens a socket at the given host and port, and if no error occures the conclusion is that the host or service is up.

Run the ping

$ping->run();

Nothing display? Don't be worry: by default if no callback function is given, PHP Pinger will ping hosts but display nothing.
To display the result, see next paragraph.

The run() method must be called at the end, otherwise other options will not be set.

Register a callback function

The callback function is called when a host has been pinged, that means the function is called for each host you added.

The callback function takes four parameters:

• $online [boolean]
  TRUE if the host has been reached
• $host [string]
  hostname checked
• $port [int]
  port used to check the host
• $label [string]
  sweety name for the host

function myCallbackFunction($online, $host, $port, $label) {
    // the callback you want, for example:
    echo '<li>', $label, ' is ', ($online ? 'online' : 'offline'),
        ' (', $host, ':', $port, ')', '</li>';
}

Once definied, you have to add it to the created instance by:

$ping->registerCallback('myCallbackFunction');

Register pre/post run callbacks

Such as you registred the previous callback function, you can register a callback function executed before the run, and/or a callback function executed after the run:

// register an action done before run:
$ping->registerPreRun('myPreRunFunction');

// register an action done after run:
$ping->registerPostRun('myPostRunFunction');

You can combine all callbacks:

$ping->registerPreRun('myPreRun')
    ->registerCallback('myCallback')
    ->registerPostRun('myPostRun');

Notifications

If your web server can send e-mail, you can be notify by e-mail. Notifications are by default disable.

Notifications levels

Three levels of notifications are available:

• NotificationLevel::NONE
  No notifications are sent (similar to disabled)
• NotificationLevel::PROBLEMS
  An e-mail is sent only if one or more hosts are down
• NotificationLevel::REPORT
  After each run, an e-mail is sent to report results

Set destinators to notify

To enable notifications, you have to add at least one destinator for e-mail:

$ping->setNotificationTo(array('your-email@domain.tld'));

Notifications could be sent to several e-mails:

$ping->setNotificationTo(array(
    'your-email@domain.tld',
    'other-email@domain.tld',
    'boss@domain.tld'
));

Enable notifications

Just add the following line:

$ping->enableNotification();

By default, enabling notifications will set the level to NotificationLevel::PROBLEMS.
You can specify another level, just add it as a parameter:

// enable PROBLEMS level (similar to previous line)
$ping->enableNotification(NotificationLevel::PROBLEMS);

// enable REPORT level
$ping->enableNotification(NotificationLevel::REPORT);

Disable notifications

You have two ways to do that:

// dedicated method:
$ping->disableNotification();

// or use the level NONE:
$ping->enableNotification(NotificationLevel::NONE);
    

Personalize the subject's preffix

When an e-mail is sent, the default preffix is Status. You can change it with:

$ping->setNotificationPreffix('Network Monitoring');

Add an e-mail signature

To add a text at the end of the e-mail sent, just add:

$ping->setNotificationSignature('--'.PHP_EOL.'By PHP Pinger');

TL;DR

// load PHP Pinger
require 'phppinger.class.php';

/* callbacks for example */
function callback($is_online, $hostname, $port, $sweety_name) {
    echo '<li>', $hostname, ':', $port, ' is ',
    ($is_online ? 'online' : 'offline'), '</li>';
}
function preRun() { echo '<ul>', PHP_EOL; }
function postRun() { echo '</ul>', PHP_EOL; }

/* instanciate a new Pinger and run it with callbacks and notifications */
$ping = new PHP_Pinger();
$ping->registerCallback('callback')
    ->registerPreRun('preRun')
    ->registerPostRun('postRun')
    ->addHost('nicolabricot.com')
    ->addHost('blog.nicolabricot.com', 80)
    ->addHost('ftp.github.com', 21, 'GitHub FTP')
    ->setNotificationTo(array('email@domain.tld', 'other-dude@domain.tld'))
    ->setNotificationPreffix('Network Monitoring')
    ->setNotificationSignature('--'.PHP_EOL.'By PHP Pinger')
    ->enableNotification(NotificationLevel::REPORT)
    ->run();

You can combine methods as you want, except the run() method which must be at the end.