The Raygun4PHP provider

Raygun4PHP is a library that you can easily add to your PHP-based website, which will then allow you to transmit all errors and exceptions to your Raygun.io dashboard. Installation is painless, and configuring your site to transmit errors takes only 5 minutes.

Raygun4PHP only requires that the server has PHP5.3 (or greater) and curl installed. The package manager Composer is optional, but if it is available installation is simple.

What can I send to Raygun.io?

Raygun4PHP is designed to send both classical PHP errors, as well as PHP5 exception objects. Send() functions are available for both of these, that call a Send() that takes an ErrorException, which is also publically available. You can add a set of tags (as an array of strings) to identify a certain type of message, or add a custom user data (as an associative array). Dedicated functions for sending messages to Raygun instead of errors or exceptions are coming soon.

Lightning-quick asynchronous error sending

For supported platforms (*nix, OS X, some Windows) the PHP provider has fully asynchronous, non-blocking sending logic. This ensures the user recieves the requested page without having to wait for the server to send its error message to Raygun. Many of our competitors post their messages in a blocking way, leading to slow load times for the user. With Raygun your site remains highly responsive while it transmits error data.

Installation

Firstly, ensure that curl is installed and enabled in your server's php.ini file.

With Composer

Composer is a package management tool for PHP which automatically fetches dependencies and also supports autoloading - this is a low-impact way to get Raygun4php into your site.

  1. If you use a *nix environment, follow the instructions to install Composer. Windows users can run this installer to automatically add it to the path etc.
  2. Inside your project's root directory create a composer.json file, containing:

    {
        "require": {
            "mindscape/raygun4php": "1.*"
        }
    }
  3. From your shell run php composer.phar install (*nix) or composer install (Windows). This will download Raygun4Php and create the appropriate autoload data.
  4. Then in a PHP file just add this, and the library will be ready for use:

    require_once 'vendor/autoload.php';

Manually with Git

Clone this repository and copy src/Raygun4php into an appropriate subdirectory in your project, such as /vendor/Raygun4php. Add requires definitions for RaygunClient.php where you want to make a call to Send().

require (dirname(dirname(__FILE__)).'/vendor/Raygun4php/RaygunClient.php');

Usage

You can send both PHP errors and object-oriented exceptions to Raygun. An easy way to accomplish this is to create a file containing exception and error handlers which make calls to the appropriate Raygun4php functions. As above, import Raygun4php - if you're using Composer, just add require_once 'vendor/autoload.php', or if not manually import RaygunClient.php. Then, create handlers that look like this:

namespace
{
    // paste your 'requires' statement

    $client = new \Raygun4php\RaygunClient("apikey for your application");

    function error_handler($errno, $errstr, $errfile, $errline ) {
        global $client;
        $client->SendError($errno, $errstr, $errfile, $errline);
    }

    function exception_handler($exception)
    {
        global $client;
        $client->SendException($exception);
    }

    set_exception_handler('exception_handler');
    set_error_handler("error_handler");
}

Note that if you are placing in inside a file with a namespace of your choosing, the above code should be declared to be within the global namespace (thus the namespace { } is required). You will also need whichever requires statement as above (autoload or manual) before the $client instantiation. Copy your application's API key from the Raygun.io dashboard, and place it in the constructor call as above (do not include the curly brackets). If the handlers reside in their own file, just import it in every file where you'd like exceptions and errors to be sent, and they will be delivered to Raygun.io.

Documentation

View the complete Raygun4PHP documentation here, including asynchronous sending info, debug mode, version numbers, user tracking and more.

Raygun4PHP GitHub Repository

For complete installation instructions, getting the source code and troubleshooting, visit the GitHub repository here.