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