view release on metacpan or  search on metacpan

lib/CGI/Alert.pm  view on Meta::CPAN

    printf <<EOP, __PACKAGE__			unless $DEBUG_SENDMAIL;
<hr>
<address>Handled by <samp>%s v$VERSION</samp></address>
</body>
</html>
EOP

    exit 0;
};
$SIG{__DIE__} = \&_die;

# END   compile-time execution
###############################################################################
# BEGIN caller-accessible functions (not yet exported)

#######################
#  emit_http_headers  #  Caller can tell us when to emit 'Status', etc
#######################
sub emit_http_headers($) {
    $Emit_HTTP_Headers = 0 + $_[0];
}

########################
#  extra_html_headers  #  Caller can give us stylesheets, etc
########################
sub extra_html_headers(@) {
    @Extra_HTML_Headers = @_;
}


#########################
#  custom_browser_text  #  Caller can give us a custom text to display
#########################
sub custom_browser_text($) {
    $Browser_Text = shift;
}


# END   caller-accessible functions (not yet exported)
###############################################################################

1;

__END__


###############################################################################
#
# Documentation
#


=head1	NAME

CGI::Alert - report CGI script errors to maintainer

=head1	SYNOPSIS

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

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

Or:

    use CGI::Alert qw(you@your.domain http_die);
    ...
    my $foo = param('foo')
      or http_die '400 Bad Request', '<b>foo</b> param missing';

The B<http_die> function provides a one-call mechanism for emitting
an HTTP error status with a helpful message.  This is intended
mostly for handling B<assert>-style situations: you want to make
sure you don't continue past a bad point.


=head1	DESCRIPTION

CGI::Alert will inform you by email of warnings and errors (from B<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 B<warnings> (either
directly via C<warn>, or by Perl itself from the C<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 B<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.

CGI::Alert is useful for letting you know of problems in your
scripts.  It's also useful for adding FIXMEs: you can leave
unimportant-seeming sections unimplemented, but put a "warn"
statement in them.  If you get email from that section, you
know your users have a need for that functionality.

=head2	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

=head2	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 B<hide=qr/.../> keyword on the import line:

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