ankane / exceptional-php

Exceptional for PHP

Exceptional PHP

The power of Exceptional for PHP

Super simple setup

require "path/to/exceptional.php";
Exceptional::setup("YOUR-API-KEY");

You can turn off exception notifications by passing an empty string as the API key. This is great for development.

if (PHP_ENV == "production") {
  $api_key = "YOUR-API-KEY";
}
else {
  $api_key = "";
}

Exceptional::setup($api_key);

You can turn on SSL by setting the second parameter to true.

Exceptional::setup($api_key, true);

Filtering sensitive data

You can blacklist sensitive fields from being submitted to Exceptional:

Exceptional::setup($api_key);
Exceptional::blacklist(array('password', 'creditcardnumber'));

Exceptions and errors

Exceptional PHP catches both errors and exceptions. You can control which errors are caught. If you want to ignore certain errors, use error_reporting(). Here's a common setting:

error_reporting(E_ALL & ~E_NOTICE);  // ignore notices

Custom error and exception handlers are supported - see examples/advanced.php.

Fatal and parse errors are caught, too - as long the setup file parses correctly.

404 support

Add the following code to your 404 handler to track 404 errors:

throw new Http404Error();

Send extra data with your exceptions

$context = array(
    "user_id" => 1
);
Exceptional::context($context);

See the Exceptional documentation for more details.

Controller + action support

You can include the controller and action names in your exceptions for easier debugging.

Exceptional::$controller = "welcome";
Exceptional::$action = "index";

Proxy server

You can send exceptions through proxy server (no support for authentication).

Exceptional::proxy($host, $port);

exceptional-php's Issues

Please strip PHP_AUTH_PW from $_SERVER environment

In ExceptionalEnvironment::to_array you remove some keys and values from the $_SERVER . Please add PHP_AUTH_PW to the list of keys that are stripped to prevent HTTP Auth passwords from being sent to Exceptional. http://php.net/manual/en/features.http-auth.php

Optionally track controller and action

Exceptional uses the controller and action parameters as part of the data it uses to group exceptions. For this and other reasons, it would be nice to be able to track that information when applicable. I've made a few small changes (quasi-diff below) to support this, which you might consider adding to the official distribution. With this change, one can simply assign Exceptional::$controller and/or Exceptional::$action to have that data passed along to the service.

exceptional.php: 
+    static $controller = "";
+    static $action = "";

exceptional/exceptional/data.php:
         $data["request"] = array(
             "url" => "$protocol$_SERVER[HTTP_HOST]$_SERVER[REQUEST_URI]",
-            "controller" => "",
-            "action" => "",
+            "controller" => Exceptional::$controller,
+            "action" => Exceptional::$action,
             "parameters" => $params,
             "request_method" => strtolower($_SERVER["REQUEST_METHOD"]),
             "remote_ip" => $_SERVER["REMOTE_ADDR"],

Exceptional::$host change.

There seems to be a API host change; see: publish docs at the bottom.

It was: plugin.getexceptional.com
.. and now it should be: api.getexceptional.com

Undefined Offset errors reported as exceptional.php errors

With additional of logging the $data at line 85 in current version of data.php I have located multiple instances which report PHPNotice of undefined offsets: (see example which follows:

Array
(
[client] => Array
(
[name] => exceptional-php
[version] => 1.5
[protocol_version] => 6
)

[application_environment] => Array
    (
        [environment] => production
        [env] => Array
            (
                [MONIT_DATE] => Thu, 19 Jan 2012 12:23:59 -0500
                [T] => regress
                [MONIT_HOST] => pro1.local
                [PATH] => /bin:/usr/bin:/sbin:/usr/sbin
                [PWD] => /www/sp.regress
                [MONIT_PROCESS_PID] => 0
                [MONIT_EVENT] => Started
                [MONIT_PROCESS_MEMORY] => 0
                [SHLVL] => 2
                [MONIT_PROCESS_CPU_PERCENT] => 0
                [MONIT_SERVICE] => SPBackgrounder4
                [MONIT_PROCESS_CHILDREN] => 0
                [MONIT_DESCRIPTION] => Started
                [_] => files/code.sp/miscincludes/SPBackgrounder.inc.php
                [OLDPWD] => /www/sp.regress/files/scripts
                [__CF_USER_TEXT_ENCODING] => 0x1F7:0:0
            )

        [host] => pro1.local
        [run_as_user] => UNKNOWN
        [application_root_directory] => /www/sp.regress
        [language] => php
        [language_version] => 5.3.6
        [framework] => 
        [libraries_loaded] => Array
            (
            )

    )

[exception] => Array
    (
        [exception_class] => PhpNotice
        [message] => Undefined offset: 59
        [backtrace] => Array
            (
                [0] => /private/var/hosts/regress/releases/20120119172154/files/except/exceptional.php:71:in `handle_error\'
            )

        [occurred_at] => 2012-01-19T12:47:15-05:00
    )

)

These always report the exception as exception.php:71, with an offset value (like 59 above) which varies. My inference is these are reported during a shutdown, as the context is a CLI based agent that does an exit(1) when it determines that the codebase has been altered and therefore gracefully exists. This exit will cause the MONIT application to detect it is no longer running and restart the CLI based PHP code thereby starting it with freshest source files.

I have 25 of these agents (SPBackgrounder###) CLI processes running and when they exit I get 25 of these reported exceptions.

I could infer that the error_get_last() call is getting some prior undefined offset which was not reported (not sure how likely that is), but with 949 locations where in MY code there is a '$array[$xxx]' style reference where $xxx is a variable and potentially numeric , and not rechecked using array_key_exists() I will have a hard time isolating this if it is from my code.

I would appreciate some guidance on how to track these phantom errors down so that I can eliminate them.

() nil exception

I am looking for some guidance. I have been using the exceptional(!)-php interface for a few months now and enjoying it, but I am getting exceptions reported at get exceptional.com frequently that look like (screenshot sorta from get exceptional.com):

BACK TO OPEN EXCEPTIONS

() nil

11 hours ago
2 months old
Number of exceptions: 2942 Number of comments:0

() nil

Occurrences

NEWER 10 of 30 OLDER
Time
07 Dec at 11:17AM
Params

{ }

---

Given the total lack of details I am trying to figure out how to identify whether these are...

1- My code doing something odd in throwing an exception (my suspicion but where??)
2 - The exceptional-php interface to getexceptional.com handling an exception in a strange way ...
3 - something on getexceptional.com misrepresenting my exception

As you can see I have 2942 of these at present. I get enough exceptions using this tool that merely looking for what happened at that time is leading me nowhere, and throwing an exception in exceptional-php is probably not the proper approach. How would you suggest I locate the root cause???

Thanks for a fine interface product and any help.

Add support for using exceptional behind a proxy

Currently trying to work up my own version of this right now, but not really finding any good ways to do this. When an application is behind a proxy, exceptional fails to deliver messages. Trying to find a nice way to handle this.

Error when fatal error happens

In case of fatal erros exceptional-php throws error -

Fatal error: Class declarations may not be nested in exceptional-php/exceptional/php_errors.php on line 3

Long Running Jobs cause accumulation without reporting

I have a number of CLI jobs that run in the background and was having issues with the Exceptions not reported to getexceptional.com until the job was terminated. This caused memory expansion (duh!) and delays in the timestamps of the reporting relative to their true occurrence.

I made a modification to the code to add a static method for flushing the exceptions list if any directly, so that I could at a convenient point (end of a task, etc.) flush the exceptions to the web and resume accumulating.

This may be valuable to others.

Pass $action/$controller regardless of HTTP_HOST

I am using this fine package not only for the code that operates from my web server directly, but also for code under unit test and code that runs in the CLI as a background agent (triggered as a GEARMAN Worker).

If I specify $controller and/or $action in this non-webserver based environment, because HTTP_HOST is not defined, exceptional-php skips passing my action/controller values. IMHO these should be sent to Exceptional regardless of the web context. I understand these are essentially crafted around the web MVC paradigm, but since they are useful outside that and beyond Rails for example, they should be passed if set.