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
24 use vars qw($VERSION $AUTOLOAD),
28 $VERSION = do { my @v = '$Revision$' =~ /\d+/g;
29 shift(@v) . "." . join("_", map {sprintf "%03d", $_ } @v); };
33 C4::Context - Maintain and manipulate the context of a Koha script
39 use C4::Context("/path/to/koha.conf");
41 $config_value = C4::Context->config("config_variable");
42 $db_handle = C4::Context->dbh;
43 $stopwordhash = C4::Context->stopwords;
47 When a Koha script runs, it makes use of a certain number of things:
48 configuration settings in F</etc/koha.conf>, a connection to the Koha
49 database, and so forth. These things make up the I<context> in which
52 This module takes care of setting up the context for a script:
53 figuring out which configuration file to load, and loading it, opening
54 a connection to the right database, and so forth.
56 Most scripts will only use one context. They can simply have
62 Other scripts may need to use several contexts. For instance, if a
63 library has two databases, one for a certain collection, and the other
64 for everything else, it might be necessary for a script to use two
65 different contexts to search both databases. Such scripts should use
66 the C<&set_context> and C<&restore_context> functions, below.
68 By default, C4::Context reads the configuration from
69 F</etc/koha.conf>. This may be overridden by setting the C<$KOHA_CONF>
70 environment variable to the pathname of a configuration file to use.
78 # In addition to what is said in the POD above, a Context object is a
79 # reference-to-hash with the following fields:
82 # A reference-to-hash whose keys and values are the
83 # configuration variables and values specified in the config
84 # file (/etc/koha.conf).
86 # A handle to the appropriate database for this context.
88 # Used by &set_dbh and &restore_dbh to hold other database
89 # handles for this context.
91 use constant CONFIG_FNAME => "/etc/koha.conf";
92 # Default config file, if none is specified
94 $context = undef; # Initially, no context is set
95 @context_stack = (); # Initially, no saved contexts
98 # Reads the specified Koha config file. Returns a reference-to-hash
99 # whose keys are the configuration variables, and whose values are the
100 # configuration values (duh).
101 # Returns undef in case of error.
104 my $fname = shift; # Config file to read
105 my $retval = {}; # Return value: ref-to-hash holding the
108 open (CONF, $fname) or return undef;
112 my $var; # Variable name
113 my $value; # Variable value
116 s/#.*//; # Strip comments
117 next if /^\s*$/; # Ignore blank lines
119 # Look for a line of the form
121 if (!/^\s*(\w+)\s*=\s*(.*?)\s*$/)
123 # FIXME - Complain about bogus line
127 # Found a variable assignment
128 # FIXME - Ought to complain is this line sets a
129 # variable that was already set.
132 $retval->{$var} = $value;
142 my $conf_fname = shift; # Config file name
145 # Create a new context from the given config file name, if
146 # any, then set it as the current context.
147 $context = new C4::Context($conf_fname);
148 return undef if !defined($context);
149 $context->set_context;
154 $context = new C4::Context;
155 $context = new C4::Context("/path/to/koha.conf");
157 Allocates a new context. Initializes the context from the specified
158 file, which defaults to either the file given by the C<$KOHA_CONF>
159 environment variable, or F</etc/koha.conf>.
161 C<&new> does not set this context as the new default context; for
162 that, use C<&set_context>.
169 my $conf_fname = shift; # Config file to load
172 # check that the specified config file exists
173 undef $conf_fname unless (defined $conf_fname && -e $conf_fname);
174 # Figure out a good config file to load if none was specified.
175 if (!defined($conf_fname))
177 # If the $KOHA_CONF environment variable is set, use
178 # that. Otherwise, use the built-in default.
179 $conf_fname = $ENV{"KOHA_CONF"} ||
182 $self->{"config_file"} = $conf_fname;
184 # Load the desired config file.
185 $self->{"config"} = &read_config_file($conf_fname);
186 return undef if !defined($self->{"config"});
188 $self->{"dbh"} = undef; # Database handle
189 $self->{"stopwords"} = undef; # stopwords list
197 $context = new C4::Context;
198 $context->set_context();
200 set_context C4::Context $context;
203 restore_context C4::Context;
205 In some cases, it might be necessary for a script to use multiple
206 contexts. C<&set_context> saves the current context on a stack, then
207 sets the context to C<$context>, which will be used in future
208 operations. To restore the previous context, use C<&restore_context>.
215 my $new_context; # The context to set
217 # Figure out whether this is a class or instance method call.
219 # We're going to make the assumption that control got here
220 # through valid means, i.e., that the caller used an instance
221 # or class method call, and that control got here through the
222 # usual inheritance mechanisms. The caller can, of course,
223 # break this assumption by playing silly buggers, but that's
224 # harder to do than doing it properly, and harder to check
226 if (ref($self) eq "")
228 # Class method. The new context is the next argument.
229 $new_context = shift;
231 # Instance method. The new context is $self.
232 $new_context = $self;
235 # Save the old context, if any, on the stack
236 push @context_stack, $context if defined($context);
238 # Set the new context
239 $context = $new_context;
242 =item restore_context
246 Restores the context set by C<&set_context>.
254 if ($#context_stack < 0)
257 die "Context stack underflow";
260 # Pop the old context and set it.
261 $context = pop @context_stack;
263 # FIXME - Should this return something, like maybe the context
264 # that was current when this was called?
269 $value = C4::Context->config("config_variable");
271 $value = C4::Context->config_variable;
273 Returns the value of a variable specified in the configuration file
274 from which the current context was created.
276 The second form is more compact, but of course may conflict with
277 method names. If there is a configuration variable called "new", then
278 C<C4::Config-E<gt>new> will not return it.
285 my $var = shift; # The config variable to return
287 return undef if !defined($context->{"config"});
288 # Presumably $self->{config} might be
289 # undefined if the config file given to &new
290 # didn't exist, and the caller didn't bother
291 # to check the return value.
293 # Return the value of the requested config variable
294 return $context->{"config"}{$var};
299 $sys_preference = C4::Context->preference("some_variable");
301 Looks up the value of the given system preference in the
302 systempreferences table of the Koha database, and returns it. If the
303 variable is not set, or in case of error, returns the undefined value.
307 # FIXME - The preferences aren't likely to change over the lifetime of
308 # the script (and things might break if they did change), so perhaps
309 # this function should cache the results it finds.
313 my $var = shift; # The system preference to return
314 my $retval; # Return value
315 my $dbh = C4::Context->dbh; # Database handle
316 my $sth; # Database query handle
318 # Look up systempreferences.variable==$var
319 $retval = $dbh->selectrow_array(<<EOT);
321 FROM systempreferences
322 WHERE variable='$var'
329 # This implements C4::Config->foo, and simply returns
330 # C4::Context->config("foo"), as described in the documentation for
333 # FIXME - Perhaps this should be extended to check &config first, and
334 # then &preference if that fails. OTOH, AUTOLOAD could lead to crappy
335 # code, so it'd probably be best to delete it altogether so as not to
336 # encourage people to use it.
341 $AUTOLOAD =~ s/.*:://; # Chop off the package name,
342 # leaving only the function name.
343 return $self->config($AUTOLOAD);
347 # Internal helper function (not a method!). This creates a new
348 # database connection from the data given in the current context, and
352 my $db_driver = $context->{"config"}{"db_scheme"} || "mysql";
353 # FIXME - It should be possible to use "MySQL" instead
354 # of "mysql", "PostgreSQL" instead of "Pg", and so
356 my $db_name = $context->{"config"}{"database"};
357 my $db_host = $context->{"config"}{"hostname"};
358 my $db_user = $context->{"config"}{"user"};
359 my $db_passwd = $context->{"config"}{"pass"};
361 return DBI->connect("DBI:$db_driver:$db_name:$db_host",
362 $db_user, $db_passwd);
367 $dbh = C4::Context->dbh;
369 Returns a database handle connected to the Koha database for the
370 current context. If no connection has yet been made, this method
371 creates one, and connects to the database.
373 This database handle is cached for future use: if you call
374 C<C4::Context-E<gt>dbh> twice, you will get the same handle both
375 times. If you need a second database handle, use C<&new_dbh> and
376 possibly C<&set_dbh>.
384 # If there's already a database handle, return it.
385 return $context->{"dbh"} if defined($context->{"dbh"});
387 # No database handle yet. Create one.
388 $context->{"dbh"} = &_new_dbh();
390 return $context->{"dbh"};
395 $dbh = C4::Context->new_dbh;
397 Creates a new connection to the Koha database for the current context,
398 and returns the database handle (a C<DBI::db> object).
400 The handle is not saved anywhere: this method is strictly a
401 convenience function; the point is that it knows which database to
402 connect to so that the caller doesn't have to know.
415 $my_dbh = C4::Connect->new_dbh;
416 C4::Connect->set_dbh($my_dbh);
418 C4::Connect->restore_dbh;
420 C<&set_dbh> and C<&restore_dbh> work in a manner analogous to
421 C<&set_context> and C<&restore_context>.
423 C<&set_dbh> saves the current database handle on a stack, then sets
424 the current database handle to C<$my_dbh>.
426 C<$my_dbh> is assumed to be a good database handle.
435 # Save the current database handle on the handle stack.
436 # We assume that $new_dbh is all good: if the caller wants to
437 # screw himself by passing an invalid handle, that's fine by
439 push @{$context->{"dbh_stack"}}, $context->{"dbh"};
440 $context->{"dbh"} = $new_dbh;
445 C4::Context->restore_dbh;
447 Restores the database handle saved by an earlier call to
448 C<C4::Context-E<gt>set_dbh>.
456 if ($#{$context->{"dbh_stack"}} < 0)
459 die "DBH stack underflow";
462 # Pop the old database handle and set it.
463 $context->{"dbh"} = pop @{$context->{"dbh_stack"}};
465 # FIXME - If it is determined that restore_context should
466 # return something, then this function should, too.
471 $dbh = C4::Context->stopwords;
473 Returns a hash with stopwords.
475 This hash is cached for future use: if you call
476 C<C4::Context-E<gt>stopwords> twice, you will get the same hash without real DB access
484 # If the hash already exists, return it.
485 return $context->{"stopwords"} if defined($context->{"stopwords"});
487 # No hash. Create one.
488 $context->{"stopwords"} = &_new_stopwords();
490 return $context->{"stopwords"};
494 # Internal helper function (not a method!). This creates a new
495 # hash with stopwords
498 my $dbh = C4::Context->dbh;
500 my $sth = $dbh->prepare("select word from stopwords");
502 while (my $stopword = $sth->fetchrow_array) {
504 $stopwordlist->{$stopword} = uc($stopword);
506 return $stopwordlist;
520 Specifies the configuration file to read.
530 Andrew Arensburger <arensb at ooblick dot com>