C4/Debug.pm

   1 package C4::Debug;
   2
   3 # Copyright 2000-2002 Katipo Communications
   4 #
   5 # This file is part of Koha.
   6 #
   7 # Koha is free software; you can redistribute it and/or modify it
   8 # under the terms of the GNU General Public License as published by
   9 # the Free Software Foundation; either version 3 of the License, or
  10 # (at your option) any later version.
  11 #
  12 # Koha is distributed in the hope that it will be useful, but
  13 # WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15 # GNU General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU General Public License
  18 # along with Koha; if not, see <http://www.gnu.org/licenses>.
  19
  20 use strict;
  21 use warnings;
  22
  23 use Exporter;
  24
  25 # use CGI qw ( -utf8 );
  26 use vars qw(@ISA @EXPORT $debug $cgi_debug);
  27 # use vars qw(@EXPORT_OK %EXPORT_TAGS);
  28
  29 BEGIN {
  30         @ISA       = qw(Exporter);
  31         @EXPORT    = qw($debug $cgi_debug);
  32         # @EXPOR_OK    = qw();
  33         # %EXPORT_TAGS = ( all=>[qw($debug $cgi_debug)], );
  34 }
  35
  36 BEGIN {
  37         # this stuff needs a begin block too, since dependencies might alter their compilations
  38         # for example, adding DataDumper
  39
  40         $debug = $ENV{KOHA_DEBUG} || $ENV{DEBUG} || 0;
  41
  42         # CGI->new conflicts w/ some upload functionality,
  43         # since we would get the "first" CGI object here.
  44         # Instead we have to parse for ourselves if we want QUERY_STRING triggers.
  45         #       my $query = CGI->new();         # conflicts!
  46         #       $cgi_debug = $ENV{KOHA_CGI_DEBUG} || $query->param('debug') || 0;
  47
  48         $cgi_debug = $ENV{KOHA_CGI_DEBUG} || 0;
  49         unless ($cgi_debug or not $ENV{QUERY_STRING}) {
  50                 foreach (split /\&/,  $ENV{QUERY_STRING}) {
  51                         /^debug\=(.+)$/ or next;
  52                         $cgi_debug = $1;
  53                         last;
  54                 }
  55         }
  56         unless ($debug =~ /^\d$/) {
  57                 warn "Invalid \$debug value attempted: $debug";
  58                 $debug=1;
  59         }
  60         unless ($cgi_debug =~ /^\d$/) {
  61                 $debug and
  62                 warn "Invalid \$cgi_debug value attempted: $cgi_debug";
  63                 $cgi_debug=1;
  64         }
  65 }
  66
  67 # sub import {
  68 #       print STDERR __PACKAGE__ . " (Debug) import @_\n";
  69 #       C4::Debug->export_to_level(1, @_);
  70 # }
  71
  72 1;
  73 __END__
  74
  75 =head1 NAME
  76
  77 C4::Debug - Standardized, centralized, exported debug switches.
  78
  79 =head1 SYNOPSIS
  80
  81         use C4::Debug;
  82
  83 =head1 DESCRIPTION
  84
  85 The purpose of this module is to centralize some of the "switches" that turn debugging
  86 off and on in Koha.  Most often, this functionality will be provided via C4::Context.
  87 C4::Debug is separate to preserve the relatively stable state of Context, and
  88 because other code will use C4::Debug without invoking Context.
  89
  90 Although centralization is our intention,
  91 for logical and security reasons, several approaches to debugging need to be
  92 kept separate.  Information useful to developers in one area will not necessarily
  93 be useful or even available to developers in another area.
  94
  95 For example, the designer of template-influenced javascript my want to be able to
  96 trigger javascript's alert function to display certain variable values, to verify
  97 the template selection is being performed correctly.  For this purpose the presence
  98 of a javascript "debug" variable might be a good switch.
  99
 100 Meanwhile, where security coders (say, for LDAP Auth) will appreciate low level feedback about
 101 Authentication transactions, an environmental system variable might be a good switch.
 102 However, clearly we would not want to expose that same information (e.g., entire LDAP records)
 103 to the web interface based on a javascript variable (even if it were possible)!
 104
 105 All that is a long way of saying THERE ARE SECURITY IMPLICATIONS to turning on
 106 debugging in various parts of the system, so don't treat them all the same or confuse them.
 107
 108 =head1 VARIABLES / AREAS
 109
 110 =head2 $debug - System, general
 111 The general purpose debug switch.
 112
 113 =head3 How to Set $debug:
 114
 115 =over
 116
 117 =item environmental variable DEBUG or KOHA_DEBUG.  In bash, you might do:
 118
 119         export KOHA_DEBUG=1;
 120         perl t/Auth.t;
 121
 122 =item Keep in mind that your webserver will not be running in the same environment as your shell.
 123 However, for development purposes, the same effect can be had by using Apache's SET_ENV
 124 command with ERROR_LOG enabled for your VirtualHost.  Not intended for production systems.
 125
 126 =item You can force the value from perl directly, like:
 127
 128         use C4::Debug;
 129         BEGIN { $C4::Debug::debug = 1; }
 130         # now any other dependencies that also use C4::Debug will have debugging ON.
 131
 132 =back
 133
 134 =head2 $cgi_debug (CGI params) The web-based debug switch.
 135
 136 =head3 How to Set $cgi_debug:
 137
 138 =over
 139
 140 =item From a web browser, for example by supplying a non-zero debug parameter (1 to 9):
 141
 142         http://www.mylibrary.org/cgi-bin/koha/opac-search.pl?q=history&debug=1
 143
 144 =item Or in HTML, add a similar input parameter:
 145
 146         <input type="hidden" name="debug" value="1" />
 147
 148 =item Or from shell (or Apache), set KOHA_CGI_DEBUG.
 149
 150 =back
 151
 152 The former methods mean $cgi_debug is exposed.  Do NOT use it to trigger any actions that you would
 153 not allow a (potentially anonymous) end user to perform.  Dumping sensitive data, directory listings, or
 154 emailing yourself a test message would all be bad actions to tie to $cgi_debug.
 155
 156 =head1 OTHER SOURCES of Debug Switches
 157
 158 =head2 System Preferences
 159
 160 =cut
 161
 162 =head2 Database Debug
 163
 164 Debugging at the database level might be useful.  Koha does not currently integrate any such
 165 capability.
 166
 167 =head1 CONVENTIONS
 168
 169 Debug values range from 0 to 9.  At zero (the default), debugging is off.
 170
 171 =head1 AUTHOR
 172
 173 Joe Atzberger
 174 atz AT liblime DOT com
 175
 176 =head1 SEE ALSO
 177
 178 CGI(3)
 179
 180 C4::Context
 181
 182 =cut
 183