php-probe/php-probe

PHP library allowing to simply probe/monitor any applications and services.

PhpProbe

PhpProbe is a PHP library allowing to simply probe/monitor any applications and services, and either print results or use them in code., _(*1)

Also, PhpProbe respects PSR-0/1/2 and PSR-3, meaning (among others) it can be used with any PSR-3 compliant logger (see setLogger() on Probes) like Monolog., _(*2)

Note that this library (especially because it's only a library) is not intended to be used instead of monitoring tools like Nagios, which already do the job., _(*3)

Here's an example what you can simply do with PhpProbe and a few lines of code (see php-probe-webapp for sources):, _(*4)

, _(*5)

Core concepts

A Probe (eg. Tcp, Http, Database) relies on a (compatible) Adapter (eg. Netcat, PhpCurl, PhpMysql), which will return an AdapterResponse, possibly containing data to test/check., _(*6)

At this point a Probe is considered successful if it could run successfuly (eq. TCP connection established)., _(*7)

You can also add one or more Check to check for specific conditions (eg. response time below a given value, HTTP response code ...)., _(*8)

Any PSR-3 compliant logger can also be attached to a Probe,(as Monolog), to be warned any error happening, by email for example. Monolog is shipped with several handlers that will certainly fit your needs. Each Check can have a defined log level, and therefore be handled by specific handlers., _(*9)

Usage

There are 2 ways this library can be used:, _(*10)

Standalone mode

<?php
require __DIR__ . "/../vendor/autoload.php";

error_reporting(E_ERROR | E_RECOVERABLE_ERROR);

/* TCP Probe */
$tcpProbe = new PhpProbe\Probe\TcpProbe('Google_DNS', array(), new \PhpProbe\Adapter\NetcatAdapter());
$tcpProbe->host('8.8.8.8')->port(53);

/* HTTPS Probe */
$checkerHttps = new PhpProbe\Check\HttpCheck();
$checkerHttps
    ->addCriterion('httpCode', \PhpProbe\Http\Codes::HTTP_NOT_FOUND)
    ->addCriterion('content', 'G[o]+ggle');

$logger = new \Monolog\Logger('PhpProbe');

$httpsProbe = new PhpProbe\Probe\HttpProbe('Google_HTTPS', array(), new \PhpProbe\Adapter\PhpCurlAdapter());
$httpsProbe
    ->url('https://www.google.com/')
    ->addChecker($checkerHttps)
    ->setLogger($logger);

$manager = new PhpProbe\Manager();
$manager
    ->addProbe($tcpProbe)
    ->addProbe($httpsProbe)
    ->checkAll();

See examples/standalone.php, _(*11)

Calling $manager->output(true) will print results (including success) that will look like this:, _(*12)

# Google_DNS - Success
# Google_HTTPS - Failure (Expected value '404' for 'httpCode', got '302' - Expected content 'G[o]+ggle' not found in response.)

Inside a framework/tool

$webservice = new PhpProbe\Probe\HttpProbe(
    'GitHub_HTTPS',
    array(),
    new \PhpProbe\Adapter\PhpCurlAdapter()
);

$webservice->url('https://api.github.com/repos/michael-bouvy/php-probe');

$httpChecker = new \PhpProbe\Check\HttpCheck();
$httpChecker->addCriterion('httpCode', \PhpProbe\Http\Codes::HTTP_FORBIDDEN);
$webservice->addChecker($httpChecker);

$webservice->check();

if ($webservice->hasSucceeded()) {
    // Do something cool
}

See examples/framework.php, _(*13)

No matter which way you use this library, you can load the probes from a YAML config file, like this example:, _(*14)

probes:
  Google.com_HTTP:
    type: Http
    options:
      url: http://www.google.com
      timeout: 5
    checkers:
      http:
        httpCode: 302
  Google.fr_HTTPS:
    type: Http
    options:
      url: https://www.google.fr
      timeout: 5
    checkers:
      http:
        httpCode: 200
        content: <title>Goorrgle</title>
      generic:
        responseTime: 1
  Google_DNS:
    type: Tcp
    adapter: Netcat
    options:
      host: 8.8.8.8
      port: 53
    checkers:
      generic:
        responseTime: 0.5
  MySQL_Local:
    type: Database
    options:
      host: localhost
      user: root
      password:
    checkers:
      database:
        database: [test, mysql]

See examples/config.yml, _(*15)

Then simply load the config file in your code:, _(*16)

$manager = new PhpProbe\Manager();
$manager->importConfig('my_config.yml');
$manager->checkAll();

See examples/standalone_config.php, _(*17)

Available probes, adapters & checkers

Probes rely on adapters: for instance TcpProbe can either work with PHP's fsockopen() function, or locally installed Unix utility netcat., _(*18)

Probes, adapters & their options

• TcpProbe
  • FsockopenAdapter (uses PHP's fsockopen() function)
  • NetcatAdapter (uses netcat utility)
  • Probe options:
  • host: hostname or IP without protocol (eg. 1.2.3.4)
  • port: self-explanatory
  • timeout: request timeout in seconds
• HttpProbe: check for HTTP response code or response content
  • PhpCurlAdapter (uses PHP's curl extension)
  • Probe options:
  • url: URL to check, including protocol (eg. http://www.mysite.com/mypage.php)
  • timeout: request timeout in seconds
  • headers: an array of HTTP headers to send (eg. ['Cache-control: no-cache', 'Cookie: key=value'])

• DatabaseProbe: check for database connection or existing database, _(*19)

  • PhpMysqlAdapter (uses PHP's mysql extension)
  • Probe options:
  • host: hostname or IP without protocol (eg. 1.2.3.4)
  • database: database name (not used by PhpMysqlAdapter (see checker below), will be necessary for future PostgreSQL adapter)
  • user: username
  • password: password, may be empty
  • timeout: connection timeout, not used yet
  • query: SQL query to execute (must include database) for query result check (only first column of first row is used)

• TestProbe: for testing purposes, _(*20)

  • TestAdapter

A NullAdapter is also available, always succeeding., _(*21)

These probes can be used with one or more of the following checkers:, _(*22)

Checkers and their criterions

• HttpCheck:
  • httpCode: self-explanatory
  • content: check for a given value in the response content (also works with regular expressions ; case insensitive)
• DatabaseCheck:
  • database: check for one (or multiple) existing database(s) for connected user
  • query: expected query result
• GenericCheck:
  • responseTime: check if probe's response time is below the given value
• TestCheck: for testing purposes

Installation

Using Composer

composer require php-probe/php-probe

Or manually, add the PhpProbe library to your composer.json:, _(*23)

{
    "require": {
        "php-probe/php-probe": "dev-master"
    }
}

From sources

Clone the repository in your project:, _(*24)

$ git clone https://github.com/michael-bouvy/php-probe

You can use the provided autoloader:, _(*25)

require __DIR__ . "/src/PhpProbe/Autoloader.php";
\PhpProbe\Autoloader::register();

If you already use a custom (non PSR-0 compliant) autoloader, you might want to prepend PhpProbe's autoloader to autoloaders stack. Simply pass true as argument to the register() method:, _(*26)

\PhpProbe\Autoloader::register(true);

Contributors

Special thanks to Julien CHICHIGNOUD (@juchi) for his Checkers concept and implementation., _(*27)

Testing

To run the test suite, you need composer., _(*28)

$ php composer.phar install --dev
$ vendor/bin/phpunit

License

PhpProbe is licensed under the MIT license., _(*29)