NAME

CGI::HTMLError - Perl extension for reporting fatal errors to the browser

SYNOPSIS

  use CGI::HTMLError;

  die "Error!"; # throw runtime error

  # or ..

  use CGI::HTMLError trace => 1, css => '/css/error.css';

  10 = 40; # redefine the number system (compile error).

DESCRIPTION

This module is supposed to be a debugging tool for CGI programmers. If use'd in a program it will send nice looking fatal errors to the browser including a view of the offending source and an optional stacktrace.

You can supply options to the module by supplying name => value pairs to the use statement. Currently there are 2 options:

trace

If true, show the stacktrace on the error page.

css

The URL of a stylesheet to use in the error page instead of the standard style.

SECURITY ALERT

Do not use this module in a production environment! Exposing the weaknesses of your program is very useful for the programmer when debugging, but it doesn't help to advertise them to every person wandering on the net.

EXPORT

This module does not export anything in the usual sense: it installs a $SIG{__DIE__} handler instead. See also "GOTCHAS"

GOTCHAS

Finding the right filename and line number

By default, CGI::HTMLError expects the filename and line number to be in the error message handed to the handler (normally this is $@). This gives application writers the chance to point to another file as the actual cause of the problem (for instance, using Carp). However, when no filename and line number are found in the error message, the module will try to get the information from caller(0).

If no filename can be found, only the error message and the optional stacktrace will be shown.

Security

Do not use this in a production environment! This code is strictly for debugging. Read the "SECURITY ALERT" secion.

Other DIE handlers

The $SIG{__DIE__} handler installed by this program will attempt to call earlier installed $SIG{__DIE__} handlers after its own. Some other modules (i.e. CGI::Carp) do not do this, if so try using CGI::HTMLError after the other module has installed its handler. See also "CGI::Carp"

CGI::Carp

If you use CGI::Carp and CGI::HTMLError, you MUST use CGI::Carp before this module in order to get them both working together.

        use CGI::Carp qw(croak);
        use CGI::HTMLError trace => 1;

This program also will not play nice when combined with CGI::Carp qw(-fatalsToBrowser), but it's meant as a replacement anyway, so I don't think that will be much of a problem.

Other uses of CGI::Carp should still be working as usual. See also "Other DIE handlers".

Catching exceptions

The installed handler will attempt to detect if it is called during eval by walking the caller stack and testing for an c<(eval)> frame, so programs can still use the c<eval { die () }> constructs to catch exeptions.

Because the stack has to tested for every exception, using this module in code that makes a lot of use of eval { die() } constructs will probably slow the program down.

mod_perl

Module is not written for, or tested with, mod_perl, but it should work if run under Apache::Registry.

Conflicting output

If the offending code already has output sent to the browser, the results might look horrible. Solution: gather the output before sending it or use a templating mechinism that does this for you.

Running outside a CGI environment

CGI::HTMLError checks the GATEWAY_INTERFACE environment variable to see whether to actually print HTML code. It assumes a CGI environment when $ENV{GATEWAY_INTERFACE} =~ /CGI/ (which will also be true under Apache::Registry). Otherwise the handler will not be installed. This is meant as a feature, especially when running CGI programs from the command line.

AUTHOR

Joost Diepenmaat <jdiepen@cpan.org>

COPYRIGHT AND LICENCE

Copyright (C) 2002 - 2005 Joost Diepenmaat

This module is licensed under the same terms as Perl itself.

SEE ALSO

perl. CGI, CGI::Carp, Carp, Apache::Registry and "die" in perlfunc.