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 with
  17 # Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
  18 # Suite 330, Boston, MA  02111-1307 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         #my $query = CGI->new();
  41         $debug = $ENV{KOHA_DEBUG} || $ENV{DEBUG} || 0;
  42         #$cgi_debug = $ENV{KOHA_CGI_DEBUG} || $query->param('debug') || 0;
  43         $cgi_debug = $ENV{KOHA_CGI_DEBUG} || 0;
  44         unless (0 <= $debug and $debug <= 9) {
  45                 warn "Invalid \$debug value attempted: $debug";
  46                 $debug=1;
  47         }
  48         unless (0 <= $cgi_debug and $cgi_debug <= 9) {
  49                 $debug and
  50                 warn "Invalid \$cgi_debug value attempted: $cgi_debug";
  51                 $cgi_debug=1;
  52         }
  53 }
  54
  55 # sub import {
  56 #       print STDERR __PACKAGE__ . " (Debug) import @_\n";
  57 #       C4::Debug->export_to_level(1, @_);
  58 # }
  59
  60 1;
  61 __END__
  62
  63 =head1 NAME
  64
  65         C4::Debug - Standardized, centralized, exported debug switches.
  66
  67 =head1 SYNOPSIS
  68
  69         use C4::Debug;
  70
  71 =head1 DESCRIPTION
  72
  73 The purpose of this module is to centralize some of the "switches" that turn debugging
  74 off and on in Koha.  Most often, this functionality will be provided via C4::Context.
  75 C4::Debug is separate to preserve the relatively stable state of Context, and
  76 because other code will use C4::Debug without invoking Context.
  77
  78 Although centralization is our intention,
  79 for logical and security reasons, several approaches to debugging need to be
  80 kept separate.  Information useful to developers in one area will not necessarily
  81 be useful or even available to developers in another area.
  82
  83 For example, the designer of template-influenced javascript my want to be able to
  84 trigger javascript's alert function to display certain variable values, to verify
  85 the template selection is being performed correctly.  For this purpose the presence
  86 of a javascript "debug" variable might be a good switch.
  87
  88 Meanwhile, where security coders (say, for LDAP Auth) will appreciate low level feedback about
  89 Authentication transactions, an environmental system variable might be a good switch.
  90 However, clearly we would not want to expose that same information (e.g., entire LDAP records)
  91 to the web interface based on a javascript variable (even if it were possible)!
  92
  93 All that is a long way of saying THERE ARE SECURITY IMPLICATIONS to turning on
  94 debugging in various parts of the system, so don't treat them all the same or confuse them.
  95
  96 =head1 VARIABLES / AREAS
  97
  98 =head2 $debug - System, general
  99 The general purpose debug switch.
 100
 101 =head3 How to Set $debug:
 102
 103 =over
 104
 105 =item environmental variable DEBUG or KOHA_DEBUG.  In bash, you might do:
 106
 107         export KOHA_DEBUG=1;
 108         perl t/Auth.t;
 109
 110 =item Keep in mind that your webserver will not be running in the same environment as your shell.
 111 However, for development purposes, the same effect can be had by using Apache's SET_ENV
 112 command with ERROR_LOG enabled for your VirtualHost.  Not intended for production systems.
 113
 114 =item You can force the value from perl directly, like:
 115
 116         use C4::Debug;
 117         use C4::Dates;
 118         BEGIN { $C4::Debug::debug = 1; }
 119         # now any other dependencies that also use C4::Debug will have debugging ON.
 120
 121 =back
 122
 123 =head2 $cgi_debug (CGI params) The web-based debug switch.
 124
 125 =head3 How to Set $cgi_debug:
 126
 127 =over
 128
 129 =item From a web browser, for example by supplying a non-zero debug parameter:
 130
 131         http://www.mylibrary.org/cgi-bin/koha/opac-search.pl?q=history&debug=1
 132
 133 =item Or in HTML, add a similar input parameter:
 134
 135         <input type="hidden" name="debug" value="1" />
 136
 137 =item Or from shell (or Apache), set KOHA_CGI_DEBUG.
 138
 139 =back
 140
 141 The former methods mean $cgi_debug is exposed.  Do NOT use it to trigger any actions that you would
 142 not allow a (potentially anonymous) end user to perform.
 143
 144 =head1 OTHER SOURCES of Debug Switches
 145
 146 =head2 System Preferences
 147
 148 =head2 Database Debug
 149
 150 Debugging at the database level might be useful.  Koha does not currently integrate any such
 151 capability.
 152
 153 =head1 CONVENTIONS
 154
 155 Debug values range from 0 to 9.  At zero (the default), debugging is off.
 156
 157 =head1 AUTHOR
 158
 159 Joe Atzberger
 160 atz AT liblime DOT com
 161
 162 =head1 SEE ALSO
 163
 164 CGI(3)
 165
 166 C4::Context
 167
 168 =cut
 169