NAME

CGI::Alert - report CGI script errors to maintainer

SYNOPSIS

    use CGI::Alert 'youraddress@your.domain';

That's all. Everything else is transparent to your script.

DESCRIPTION

CGI::Alert will inform you by email of warnings and errors (from die or from exiting with nonzero status).

If the script terminates normally (exit status 0), and no warnings were issued by the script or by Perl, CGI::Alert is a no-op. It just consumes resources but has no other effect.

If the script terminates normally, but has issued warnings (either directly via warn, or by Perl itself from the warnings pragma), CGI::Alert will send you an email message with the first 10 of those warnings, plus other details (see below).

If the script terminates via die, CGI::Alert sends you an email message with the details. It also displays a big 'Uh-Oh' on the remote web user's browser, informing him/her that an error has occurred, and that the maintainer has been notified.

Maintainer Address

To specify the email address that will be notified of problems, include it in the import list:

    use CGI::Alert 'esm@pobox.com';

or, more typically:

    use CGI::Alert 'esm';   # where 'esm' is a local account

Hiding Sensitive Data

Forms often contain sensitive data: passwords, credit card numbers, next Tuesday's winning Lotto numbers. CGI::Alert sends unencrypted email, and you don't want these values being intercepted.

To exclude CGI parameters from the list sent by email, use the hide=qr/.../ keyword on the import line:

    use CGI::Alert 'esm', 'hide=qr/credit/i';

If CGI::Alert encounters any parameter matching the given regex, it substitutes [...] (bracket, ellipsis, bracket) for its value:

    card_type       = Visa
    card_name       = Joe Bob
    credit_card_num = [...]

Multiple expressions are allowed, but must be specified using one hide= for each:

    use CGI::Alert 'esm', 'hide=qr/credit/i', 'hide=qr/passphrase/';

The default exclusion list is qr/[\b_-]passw/i

Running under tilde URLs

CGI::Alert checks the REQUEST_URI environment variable. If it detects a URL of the form /~something (slash, tilde, something) CGI::Alert overrides the maintainer address, sending email only to the something following the tilde.

Specifics: email

On any die, or if the CGI script has issued warnings, CGI::Alert sends an email message to the maintainer with the following details:

• The URL used to access the page

• The error message emitted by die, with complete stack trace.

• Any warnings issued by the script (well, just the first 10), with full stack trace.

• The remote user name (if known) and host name/address

• A full list of CGI parameters passed to the script. CGI::Alert relies on the param function provided by CGI.pm for this.

• A full list of process environment variables and their settings.

• The expanded results of %INC, showing all loaded modules and their paths. This can help when the problem is an obsolete version of a module.

Specifics: WWW

If the script dies, a large heading will be shown in red typeface, saying "Uh-Oh!". The error will be displayed, along with a note saying that the maintainer has been notified by email.

The remote (web) user is not informed of warnings.

REQUIREMENTS

CGI::Alert requires a properly configured sendmail executable in /usr/sbin or /usr/lib. This does not need to be Sendmail itself: Postfix, Exim, and other MTAs provide this executable.

BUGS

If the script dies before emitting the 'Status' and 'Content-Type' headers (e.g. because of a compile-time syntax error), the remote user will see the dreaded '500 Server Error' page. Since this only really happens when the CGI script fails to compile, this will only ever be seen by the CGI script developer and hence is not a big deal.

As a workaround for this, you can do:

    CGI::Alert::emit_http_headers(1);

This tells CGI::Alert to emit HTTP Status and Content-type headers before displaying the Uh-Oh message.

AUTHOR

Ed Santiago <esm@pobox.com>

cpanm CGI::Alert

perl -MCPAN -e shell
install CGI::Alert