1 # Copyright 2002 Katipo Communications
3 # This file is part of Koha.
5 # Koha is free software; you can redistribute it and/or modify it under the
6 # terms of the GNU General Public License as published by the Free Software
7 # Foundation; either version 2 of the License, or (at your option) any later
10 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
11 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
12 # A PARTICULAR PURPOSE. See the GNU General Public License for more details.
14 # You should have received a copy of the GNU General Public License along with
15 # Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
16 # Suite 330, Boston, MA 02111-1307 USA
22 use vars qw($VERSION $AUTOLOAD),
26 $VERSION = do { my @v = '$Revision$' =~ /\d+/g;
27 shift(@v) . "." . join("_", map {sprintf "%03d", $_ } @v); };
31 C4::Context - Maintain and manipulate the context of a Koha script
37 use C4::Context("/path/to/koha.conf");
39 $config_value = C4::Context->config("config_variable");
40 $db_handle = C4::Context->dbh;
44 When a Koha script runs, it makes use of a certain number of things:
45 configuration settings in F</etc/koha.conf>, a connection to the Koha
46 database, and so forth. These things make up the I<context> in which
49 This module takes care of setting up the context for a script:
50 figuring out which configuration file to load, and loading it, opening
51 a connection to the right database, and so forth.
53 Most scripts will only use one context. They can simply have
59 Other scripts may need to use several contexts. For instance, if a
60 library has two databases, one for a certain collection, and the other
61 for everything else, it might be necessary for a script to use two
62 different contexts to search both databases. Such scripts should use
63 the C<&set_context> and C<&restore_context> functions, below.
65 By default, C4::Context reads the configuration from
66 F</etc/koha.conf>. This may be overridden by setting the C<$KOHA_CONF>
67 environment variable to the pathname of a configuration file to use.
75 # In addition to what is said in the POD above, a Context object is a
76 # reference-to-hash with the following fields:
79 # A reference-to-hash whose keys and values are the
80 # configuration variables and values specified in the config
81 # file (/etc/koha.conf).
83 # A handle to the appropriate database for this context.
85 # Used by &set_dbh and &restore_dbh to hold other database
86 # handles for this context.
88 use constant CONFIG_FNAME => "/etc/koha.conf";
89 # Default config file, if none is specified
91 $context = undef; # Initially, no context is set
92 @context_stack = (); # Initially, no saved contexts
95 # Reads the specified Koha config file. Returns a reference-to-hash
96 # whose keys are the configuration variables, and whose values are the
97 # configuration values (duh).
98 # Returns undef in case of error.
101 my $fname = shift; # Config file to read
102 my $retval = {}; # Return value: ref-to-hash holding the
105 open (CONF, $fname) or return undef;
109 my $var; # Variable name
110 my $value; # Variable value
113 s/#.*//; # Strip comments
114 next if /^\s*$/; # Ignore blank lines
116 # Look for a line of the form
118 if (!/^\s*(\w+)\s*=\s*(.*?)\s*$/)
120 # FIXME - Complain about bogus line
124 # Found a variable assignment
125 # FIXME - Ought to complain is this line sets a
126 # variable that was already set.
129 $retval->{$var} = $value;
139 my $conf_fname = shift; # Config file name
142 # Create a new context from the given config file name, if
143 # any, then set it as the current context.
144 $context = new C4::Context($conf_fname);
145 return undef if !defined($context);
146 $context->set_context;
151 $context = new C4::Context;
152 $context = new C4::Context("/path/to/koha.conf");
154 Allocates a new context. Initializes the context from the specified
155 file, which defaults to either the file given by the C<$KOHA_CONF>
156 environment variable, or F</etc/koha.conf>.
158 C<&new> does not set this context as the new default context; for
159 that, use C<&set_context>.
166 my $conf_fname = shift; # Config file to load
169 # Figure out a good config file to load if none was specified.
170 if (!defined($conf_fname))
172 # If the $KOHA_CONF environment variable is set, use
173 # that. Otherwise, use the built-in default.
174 $conf_fname = $ENV{"KOHA_CONF"} ||
178 $self->{"config_file"} = $conf_fname;
180 # Load the desired config file.
181 $self->{"config"} = &read_config_file($conf_fname);
182 return undef if !defined($self->{"config"});
184 $self->{"dbh"} = undef; # Database handle
185 $self->{"stopwords"} = undef; # stopwords list
193 $context = new C4::Context;
194 $context->set_context();
196 set_context C4::Context $context;
199 restore_context C4::Context;
201 In some cases, it might be necessary for a script to use multiple
202 contexts. C<&set_context> saves the current context on a stack, then
203 sets the context to C<$context>, which will be used in future
204 operations. To restore the previous context, use C<&restore_context>.
211 my $new_context; # The context to set
213 # Figure out whether this is a class or instance method call.
215 # We're going to make the assumption that control got here
216 # through valid means, i.e., that the caller used an instance
217 # or class method call, and that control got here through the
218 # usual inheritance mechanisms. The caller can, of course,
219 # break this assumption by playing silly buggers, but that's
220 # harder to do than doing it properly, and harder to check
222 if (ref($self) eq "")
224 # Class method. The new context is the next argument.
225 $new_context = shift;
227 # Instance method. The new context is $self.
228 $new_context = $self;
231 # Save the old context, if any, on the stack
232 push @context_stack, $context if defined($context);
234 # Set the new context
235 $context = $new_context;
238 =item restore_context
242 Restores the context set by C<&set_context>.
250 if ($#context_stack < 0)
253 die "Context stack underflow";
256 # Pop the old context and set it.
257 $context = pop @context_stack;
259 # FIXME - Should this return something, like maybe the context
260 # that was current when this was called?
265 $value = C4::Context->config("config_variable");
267 $value = C4::Context->config_variable;
269 Returns the value of a variable specified in the configuration file
270 from which the current context was created.
272 The second form is more compact, but of course may conflict with
273 method names. If there is a configuration variable called "new", then
274 C<C4::Config-E<gt>new> will not return it.
281 my $var = shift; # The config variable to return
283 return undef if !defined($context->{"config"});
284 # Presumably $self->{config} might be
285 # undefined if the config file given to &new
286 # didn't exist, and the caller didn't bother
287 # to check the return value.
289 # Return the value of the requested config variable
290 return $context->{"config"}{$var};
294 # This implements C4::Config->foo, and simply returns
295 # C4::Context->config("foo"), as described in the documentation for
301 $AUTOLOAD =~ s/.*:://; # Chop off the package name,
302 # leaving only the function name.
303 return $self->config($AUTOLOAD);
307 # Internal helper function (not a method!). This creates a new
308 # database connection from the data given in the current context, and
312 my $db_driver = $context->{"config"}{"db_scheme"} || "mysql";
313 my $db_name = $context->{"config"}{"database"};
314 my $db_host = $context->{"config"}{"hostname"};
315 my $db_user = $context->{"config"}{"user"};
316 my $db_passwd = $context->{"config"}{"pass"};
318 return DBI->connect("DBI:$db_driver:$db_name:$db_host",
319 $db_user, $db_passwd);
324 $dbh = C4::Context->dbh;
326 Returns a database handle connected to the Koha database for the
327 current context. If no connection has yet been made, this method
328 creates one, and connects to the database.
330 This database handle is cached for future use: if you call
331 C<C4::Context-E<gt>dbh> twice, you will get the same handle both
332 times. If you need a second database handle, use C<&new_dbh> and
333 possibly C<&set_dbh>.
341 # If there's already a database handle, return it.
342 return $context->{"dbh"} if defined($context->{"dbh"});
344 # No database handle yet. Create one.
345 $context->{"dbh"} = &_new_dbh();
347 return $context->{"dbh"};
352 $dbh = C4::Context->new_dbh;
354 Creates a new connection to the Koha database for the current context,
355 and returns the database handle (a C<DBI::db> object).
357 The handle is not saved anywhere: this method is strictly a
358 convenience function; the point is that it knows which database to
359 connect to so that the caller doesn't have to know.
372 $my_dbh = C4::Connect->new_dbh;
373 C4::Connect->set_dbh($my_dbh);
375 C4::Connect->restore_dbh;
377 C<&set_dbh> and C<&restore_dbh> work in a manner analogous to
378 C<&set_context> and C<&restore_context>.
380 C<&set_dbh> saves the current database handle on a stack, then sets
381 the current database handle to C<$my_dbh>.
383 C<$my_dbh> is assumed to be a good database handle.
392 # Save the current database handle on the handle stack.
393 # We assume that $new_dbh is all good: if the caller wants to
394 # screw himself by passing an invalid handle, that's fine by
396 push @{$context->{"dbh_stack"}}, $context->{"dbh"};
397 $context->{"dbh"} = $new_dbh;
402 C4::Context->restore_dbh;
404 Restores the database handle saved by an earlier call to
405 C<C4::Context-E<gt>set_dbh>.
413 if ($#{$context->{"dbh_stack"}} < 0)
416 die "DBH stack underflow";
419 # Pop the old database handle and set it.
420 $context->{"dbh"} = pop @{$context->{"dbh_stack"}};
422 # FIXME - If it is determined that restore_context should
423 # return something, then this function should, too.
428 $dbh = C4::Context->stopwords;
430 Returns a hash with stopwords.
432 This hash is cached for future use: if you call
433 C<C4::Context-E<gt>stopwords> twice, you will get the same hash without real DB access
441 # If the hash already exists, return it.
442 return $context->{"stopwords"} if defined($context->{"stopwords"});
444 # No hash. Create one.
445 $context->{"stopwords"} = &_new_stopwords();
447 return $context->{"stopwords"};
451 # Internal helper function (not a method!). This creates a new
452 # hash with stopwords
457 my $sth = $dbh->prepare("select word from stopwords");
459 while (my $stopword = $sth->fetchrow_array) {
461 $stopwordlist->{$stopword} = uc($stopword);
463 return $stopwordlist;
464 # my $db_driver = $context->{"config"}{"db_scheme"} || "mysql";
465 # my $db_name = $context->{"config"}{"database"};
466 # my $db_host = $context->{"config"}{"hostname"};
467 # my $db_user = $context->{"config"}{"user"};
468 # my $db_passwd = $context->{"config"}{"pass"};
470 # return DBI->connect("DBI:$db_driver:$db_name:$db_host",
471 # $db_user, $db_passwd);
484 Specifies the configuration file to read.