BugsSite/Bugzilla.pm

   1 # -*- Mode: perl; indent-tabs-mode: nil -*-
   2 #
   3 # The contents of this file are subject to the Mozilla Public
   4 # License Version 1.1 (the "License"); you may not use this file
   5 # except in compliance with the License. You may obtain a copy of
   6 # the License at http://www.mozilla.org/MPL/
   7 #
   8 # Software distributed under the License is distributed on an "AS
   9 # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
  10 # implied. See the License for the specific language governing
  11 # rights and limitations under the License.
  12 #
  13 # The Original Code is the Bugzilla Bug Tracking System.
  14 #
  15 # The Initial Developer of the Original Code is Netscape Communications
  16 # Corporation. Portions created by Netscape are
  17 # Copyright (C) 1998 Netscape Communications Corporation. All
  18 # Rights Reserved.
  19 #
  20 # Contributor(s): Bradley Baetz <bbaetz@student.usyd.edu.au>
  21 #                 Erik Stambaugh <erik@dasbistro.com>
  22 #
  23
  24 package Bugzilla;
  25
  26 use strict;
  27
  28 use Bugzilla::Auth;
  29 use Bugzilla::Auth::Login::WWW;
  30 use Bugzilla::CGI;
  31 use Bugzilla::Config;
  32 use Bugzilla::Constants;
  33 use Bugzilla::DB;
  34 use Bugzilla::Template;
  35 use Bugzilla::User;
  36
  37 my $_template;
  38 sub template {
  39     my $class = shift;
  40     $_template ||= Bugzilla::Template->create();
  41     return $_template;
  42 }
  43
  44 my $_cgi;
  45 sub cgi {
  46     my $class = shift;
  47     $_cgi ||= new Bugzilla::CGI();
  48     return $_cgi;
  49 }
  50
  51 my $_user;
  52 sub user {
  53     my $class = shift;
  54
  55     if (not defined $_user) {
  56         $_user = new Bugzilla::User;
  57     }
  58
  59     return $_user;
  60 }
  61
  62 sub login {
  63     my ($class, $type) = @_;
  64     $_user = Bugzilla::Auth::Login::WWW->login($type);
  65 }
  66
  67 sub logout {
  68     my ($class, $option) = @_;
  69
  70     # If we're not logged in, go away
  71     return unless user->id;
  72
  73     $option = LOGOUT_CURRENT unless defined $option;
  74     Bugzilla::Auth::Login::WWW->logout($_user, $option);
  75 }
  76
  77 sub logout_user {
  78     my ($class, $user) = @_;
  79     # When we're logging out another user we leave cookies alone, and
  80     # therefore avoid calling Bugzilla->logout() directly.
  81     Bugzilla::Auth::Login::WWW->logout($user, LOGOUT_ALL);
  82 }
  83
  84 # just a compatibility front-end to logout_user that gets a user by id
  85 sub logout_user_by_id {
  86     my ($class, $id) = @_;
  87     my $user = new Bugzilla::User($id);
  88     $class->logout_user($user);
  89 }
  90
  91 # hack that invalidates credentials for a single request
  92 sub logout_request {
  93     undef $_user;
  94     # XXX clean this up eventually
  95     $::userid = 0;
  96     # We can't delete from $cgi->cookie, so logincookie data will remain
  97     # there. Don't rely on it: use Bugzilla->user->login instead!
  98 }
  99
 100 my $_dbh;
 101 my $_dbh_main;
 102 my $_dbh_shadow;
 103 sub dbh {
 104     my $class = shift;
 105
 106     # If we're not connected, then we must want the main db
 107     if (!$_dbh) {
 108         $_dbh = $_dbh_main = Bugzilla::DB::connect_main();
 109     }
 110
 111     return $_dbh;
 112 }
 113
 114 my $_batch;
 115 sub batch {
 116     my $class = shift;
 117     my $newval = shift;
 118     if ($newval) {
 119         $_batch = $newval;
 120     }
 121     return $_batch || 0;
 122 }
 123
 124 sub dbwritesallowed {
 125     my $class = shift;
 126
 127     # We can write if we are connected to the main database.
 128     # Note that if we don't have a shadowdb, then we claim that its ok
 129     # to write even if we're nominally connected to the shadowdb.
 130     # This is OK because this method is only used to test if misc
 131     # updates can be done, rather than anything complicated.
 132     return $class->dbh == $_dbh_main;
 133 }
 134
 135 sub switch_to_shadow_db {
 136     my $class = shift;
 137
 138     if (!$_dbh_shadow) {
 139         if (Param('shadowdb')) {
 140             $_dbh_shadow = Bugzilla::DB::connect_shadow();
 141         } else {
 142             $_dbh_shadow = $_dbh_main;
 143         }
 144     }
 145
 146     $_dbh = $_dbh_shadow;
 147     # we have to return $class->dbh instead of $_dbh as
 148     # $_dbh_shadow may be undefined if no shadow DB is used
 149     # and no connection to the main DB has been established yet.
 150     return $class->dbh;
 151 }
 152
 153 sub switch_to_main_db {
 154     my $class = shift;
 155
 156     $_dbh = $_dbh_main;
 157     # We have to return $class->dbh instead of $_dbh as
 158     # $_dbh_main may be undefined if no connection to the main DB
 159     # has been established yet.
 160     return $class->dbh;
 161 }
 162
 163 # Private methods
 164
 165 # Per process cleanup
 166 sub _cleanup {
 167     undef $_cgi;
 168     undef $_user;
 169
 170     # See bug 192531. If we don't clear the possibly active statement handles,
 171     # then when this is called from the END block, it happens _before_ the
 172     # destructors in Bugzilla::DB have happened.
 173     # See http://rt.perl.org/rt2/Ticket/Display.html?id=17450#38810
 174     # Without disconnecting explicitly here, noone notices, because DBI::END
 175     # ends up calling DBD::mysql's $drh->disconnect_all, which is a noop.
 176     # This code is evil, but it needs to be done, at least until SendSQL and
 177     # friends can be removed
 178     @Bugzilla::DB::SQLStateStack = ();
 179     undef $Bugzilla::DB::_current_sth;
 180
 181     # When we support transactions, need to ->rollback here
 182     $_dbh_main->disconnect if $_dbh_main;
 183     $_dbh_shadow->disconnect if $_dbh_shadow and Param("shadowdb");
 184     undef $_dbh_main;
 185     undef $_dbh_shadow;
 186     undef $_dbh;
 187 }
 188
 189 sub END {
 190     _cleanup();
 191 }
 192
 193 1;
 194
 195 __END__
 196
 197 =head1 NAME
 198
 199 Bugzilla - Semi-persistent collection of various objects used by scripts
 200 and modules
 201
 202 =head1 SYNOPSIS
 203
 204   use Bugzilla;
 205
 206   sub someModulesSub {
 207     Bugzilla->dbh->prepare(...);
 208     Bugzilla->template->process(...);
 209   }
 210
 211 =head1 DESCRIPTION
 212
 213 Several Bugzilla 'things' are used by a variety of modules and scripts. This
 214 includes database handles, template objects, and so on.
 215
 216 This module is a singleton intended as a central place to store these objects.
 217 This approach has several advantages:
 218
 219 =over 4
 220
 221 =item *
 222
 223 They're not global variables, so we don't have issues with them staying arround
 224 with mod_perl
 225
 226 =item *
 227
 228 Everything is in one central place, so its easy to access, modify, and maintain
 229
 230 =item *
 231
 232 Code in modules can get access to these objects without having to have them
 233 all passed from the caller, and the caller's caller, and....
 234
 235 =item *
 236
 237 We can reuse objects across requests using mod_perl where appropriate (eg
 238 templates), whilst destroying those which are only valid for a single request
 239 (such as the current user)
 240
 241 =back
 242
 243 Note that items accessible via this object are demand-loaded when requested.
 244
 245 For something to be added to this object, it should either be able to benefit
 246 from persistence when run under mod_perl (such as the a C<template> object),
 247 or should be something which is globally required by a large ammount of code
 248 (such as the current C<user> object).
 249
 250 =head1 METHODS
 251
 252 Note that all C<Bugzilla> functionality is method based; use C<Bugzilla-E<gt>dbh>
 253 rather than C<Bugzilla::dbh>. Nothing cares about this now, but don't rely on
 254 that.
 255
 256 =over 4
 257
 258 =item C<template>
 259
 260 The current C<Template> object, to be used for output
 261
 262 =item C<cgi>
 263
 264 The current C<cgi> object. Note that modules should B<not> be using this in
 265 general. Not all Bugzilla actions are cgi requests. Its useful as a convenience
 266 method for those scripts/templates which are only use via CGI, though.
 267
 268 =item C<user>
 269
 270 The current C<Bugzilla::User>. C<undef> if there is no currently logged in user
 271 or if the login code has not yet been run.
 272
 273 =item C<login>
 274
 275 Logs in a user, returning a C<Bugzilla::User> object, or C<undef> if there is
 276 no logged in user. See L<Bugzilla::Auth|Bugzilla::Auth>, and
 277 L<Bugzilla::User|Bugzilla::User>.
 278
 279 =item C<logout($option)>
 280
 281 Logs out the current user, which involves invalidating user sessions and
 282 cookies. Three options are available from
 283 L<Bugzilla::Constants|Bugzilla::Constants>: LOGOUT_CURRENT (the
 284 default), LOGOUT_ALL or LOGOUT_KEEP_CURRENT.
 285
 286 =item C<logout_user($user)>
 287
 288 Logs out the specified user (invalidating all his sessions), taking a
 289 Bugzilla::User instance.
 290
 291 =item C<logout_by_id($id)>
 292
 293 Logs out the user with the id specified. This is a compatibility
 294 function to be used in callsites where there is only a userid and no
 295 Bugzilla::User instance.
 296
 297 =item C<logout_request>
 298
 299 Essentially, causes calls to C<Bugzilla-E<gt>user> to return C<undef>. This has the
 300 effect of logging out a user for the current request only; cookies and
 301 database sessions are left intact.
 302
 303 =item C<batch>
 304
 305 Set to true, by calling Bugzilla->batch(1), to indicate that Bugzilla is
 306 being called in a non-interactive manner and errors should be passed to
 307 die() rather than being sent to a browser and finished with an exit().
 308 Bugzilla->batch will return the current state of this flag.
 309
 310 =item C<dbh>
 311
 312 The current database handle. See L<DBI>.
 313
 314 =item C<dbwritesallowed>
 315
 316 Determines if writes to the database are permitted. This is usually used to
 317 determine if some general cleanup needs to occur (such as clearing the token
 318 table)
 319
 320 =item C<switch_to_shadow_db>
 321
 322 Switch from using the main database to using the shadow database.
 323
 324 =item C<switch_to_main_db>
 325
 326 Change the database object to refer to the main database.
 327
 328 =back