The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
CGI-Debug-0_03
River stage zero No dependents
/ CGI::Debug

NAME

CGI::Debug - module for CGI programs debugging

SYNOPSIS

 use CGI::Debug;

 use CGI::Debug( report => ['errors', 'empty_body', 'time', 
                            'params', 'cookies', 'enviroment',
                            ],
                 on     => 'fatals',
                 to     => { browser => 1,
                             log     => 1,
                             file    => '/tmp/my_error',
                             mail    => ['staff@company.orb', 
                                         'webmaster',
                                         ],
                         },
                 header => 'control',
                 set    => { param_length => 60 },
                 );

DESCRIPTION

CGI::Debug will catch (almost) all compilation errors and warnings and will display them in the browser.

Just "use CGI::Debug" on the second row in your program. The module will not change the behaviour of your cgi program. As long as your program works, you will not notice the modules presence.

You can at any time remove the "use CGI::Debug" without changing the behaviour of your program. It will only run faster.

The actions of CGI::Debug is determined by, in order: 1. cookie control variables 2. enviroment control variables 3. the import control parameters 4. the defaults

Default behaviour

Report to browser:

  • bad HTTP-headers

  • empty HTTP-body

  • warnings and errors

  • elapsed time

  • query parameters

  • cookies

  • enviroment variables (max 40 chars in value)

EXAMPELS

Only report errors: use CGI::Debug( report => 'errors' );

Do not bother about warnings: use CGI::Debug( on => 'fatals' );

Allways show complete debugging info: use CGI::Debug( report => 'everything', on => 'anything' );

Send debug data as mail to file owner: use CGI::Debug( to => 'mail' );

CONTROL PARAMETERS

Cookie control variables makes it possible to control the debugging enviroment from a program in another browser window. This would be prefereble with comples web pages (framesets, etc). The page is viewd as normal in one window. All debugging data is shown i another window, that also provides controls to alter the debugging enviroment. (But this external debugging program is not yet implemented.)

Enviroment control variables makes it more easy to globaly set the debugging enviroment for a web site. It is also a way for the target program to control the CGI::Debug module actions.

The four methods can be mixed. (Import parameters, cookies, enviroment and defaults.) The module will try to make sense with whatever you give it. The possibilites of control are more limitied in the Cookie / ENV version.

report errors

  Cookie / ENV: CGI-Debug-report=errors

  Import: report => 'errors'
          report => [ 'errors', ... ]

Report the content of STDERR.

This will allways be reported. This control is for saying that none of the other defualt things will be reported.

report empty_body

  Cookie / ENV: CGI-Debug-report=empty_body

  Import: report => 'empty_body'
          report => [ 'empty_body', ... ]

Report if HTTP-body is empty.

This requires that "header control" is set.

report time

  Cookie / ENV: CGI-Debug-report=time

  Import: report => 'time'
          report => [ 'time', ... ]

Report the elapsed time from beginning to end of execution.

If Time::Hires is found, this will be given with subsecond precision.

report params

  Cookie / ENV: CGI-Debug-report=params

  Import: report => 'params'
          report => [ 'params', ... ]

Report a table of all name/value pairs, as given by the CGI module.

Multiple values will be reported as distinct pairs, in order. Values will be truncated to the "set param_length" number of chars. The total length is shown for each value.

report cookies

  Cookie / ENV: CGI-Debug-report=cookies

  Import: report => 'cookies'
          report => [ 'cookies', ... ]

Report a table of all cookies, as given by the CGI module.

Multiple values will be reported as distinct pairs, in order. Values will be truncated to the "set param_length" number of chars. The total length is shown for each value.

report enviroment

  Cookie / ENV: CGI-Debug-report=enviroment

  Import: report => 'enviroment'
          report => [ 'enviroment', ... ]

Report a table of all enviroment varialbes INCLUDING empty_body, time, params, cookies.

report everything

  Cookie / ENV: CGI-Debug-report=everything

  Import: report => 'everything'
          report => [ 'everything', ... ]

Report enviroment and all what that includes.

(The plan is for this control to include the contorl of HTML compliance.)

report internals

  Cookie / ENV: CGI-Debug-report=internals

  Import: report => 'internals'
          report => [ 'internals', ... ]

Report data for the debugging of the module itself, including everything else. Data::Dumper will be used, if found.

on fatals

  Cookie / ENV: CGI-Debug-on=fatals

  Import: on => 'fatals'

Only deliver report on fatal errors.

This will ignore warnings. CGI::Debug checks the exit value. Reports will also be delivered if an empty body is detected, in case "header control" is set.

on warnings

  Cookie / ENV: CGI-Debug-on=warnings

  Import: on => 'warnings'

Only deliver report on fatals or if there was any output to STDERR.

on anything

  Cookie / ENV: CGI-Debug-on=anything

  Import: on => 'anything'

Always deliver reports, even if there was no errors.

to browser

  Cookie / ENV: CGI-Debug-to=browser

  Import: to => 'browser'
          to => [ 'browser', ... ]
          to => { 'browser' => 1, ... }

Send report to browser.

The report will come after any program output. The module will assume the page is in text/html, unless "header control" is set, in case this will be checked. (In none HTML mode, the header and delimiter will be ASCII.)

There is many cases in which faulty or bad HTML will hide the report. This could be controled with "report html_compliance" (which is not yet implemented).

to log

  Cookie / ENV: CGI-Debug-to=log

  Import: to => 'log'
          to => [ 'log', ... ]
          to => { 'log' => 1, ... }

Send report to the standard error log.

This will easily result in a huge log.

to file

  Cookie / ENV: CGI-Debug-to=file
                CGI-Debug-to-file=filename

  Import: to => 'file'
          to => [ 'file', ... ]
          to => { 'file' => 'filename', ... }
          to => { 'file' => [ 'filename1', 'filename2', ... ] ... }

Save report to filename.

Default filename is "/tmp/CGI-Debug-error.txt". The file will be overwritten by the next report. This solution is to be used for debugging with an external program. (To be used with cookies.)

This will not work well with framesets that generates multipple reports at a time. The action of this control may change in future versions.

to mail

  Cookie / ENV: CGI-Debug-to=mail
                CGI-Debug-to-mail=mailaddress

  Import: to => 'mail'
          to => [ 'mail', ... ]
          to => { 'mail' => 'mailaddress', ... }
          to => { 'mail' => [ 'mailaddress1', 'mailaddress2', ... ] ... }

Send report with email.

The default mailaddress is the owner of the cgi program. This function requires the MIME::Lite module. (That is a greate module!)

The idea is to specify an email address that will be used if anybody besides yourself is getting an error. You will not get your own errors as email if you overide that action with a control cookie.

header control

  Cookie / ENV: CGI-Debug-header=control

  Import: header => 'control'

Controls that the HTTP-header is correct.

This control will follow the HTTP RFC to the point. It reports if the header is ok, if the content-type is text/html, and the length of the HTTP-body. That information will be used by other parts of CGI::Debug. This is done by redirecting STDOUT to a temporary file. This is the only control that must be set in the beginning of the program. All other controls can be changed during before the end of the program.

header ignore

  Cookie / ENV: CGI-Debug-header=ignore

  Import: header => 'ignore'

Assume that the HTTP-header is correct and specifies text/html.

This will tell CGI::Debug to ignore the STDOUT. A server generated error response will result if the program compile ok but does not produce a valid HTTP-header.

header minimal

  Cookie / ENV: CGI-Debug-header=minimal

  Import: header => 'minimal'

Generates a simple text/html HTTP-header for you.

This is the only action that CHANGES THE BEHAVIOUR of your program. You will have to insert your own header if you remove the CGI::Debug row. But this action will guarantee that you have a valid header, without the need to save STDOUT to a temporary file.

set param_length

  Cookie / ENV: CGI-Debug-set-param_length=value

  Import: set => { param_length => 'value', ... }

Set the max length of the parameter values.

The default length is 40 chars. This is used for query parameters, cookies and enviroment. The purpose is to give you a table that looks good.

TODO

  • Clean up and generalize configuration

  • Test on non-*nix platforms

  • Make it work with mod_perl

  • Implement HTML_compliance controls (using HTML::validate)

  • Implement function for debugging in a separate window

  • Enable custom responses for visitors on program failure

COPYRIGHT

Copyright (c) 1999 Jonas Liljegren. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Jonas Liljegren <jonas@paranormal.o.se>

SEE ALSO

CGI, MIME::Lite