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
20 # 2004-08-11 A. Tarallo: Added the function db_escheme2dbi, tested my bugfixes,
21 # further details about them in the code.
28 use vars qw($VERSION $AUTOLOAD),
32 $VERSION = do { my @v = '$Revision$' =~ /\d+/g;
33 shift(@v) . "." . join("_", map {sprintf "%03d", $_ } @v); };
37 C4::Context - Maintain and manipulate the context of a Koha script
43 use C4::Context("/path/to/koha.conf");
45 $config_value = C4::Context->config("config_variable");
46 $db_handle = C4::Context->dbh;
47 $stopwordhash = C4::Context->stopwords;
51 When a Koha script runs, it makes use of a certain number of things:
52 configuration settings in F</etc/koha.conf>, a connection to the Koha
53 database, and so forth. These things make up the I<context> in which
56 This module takes care of setting up the context for a script:
57 figuring out which configuration file to load, and loading it, opening
58 a connection to the right database, and so forth.
60 Most scripts will only use one context. They can simply have
66 Other scripts may need to use several contexts. For instance, if a
67 library has two databases, one for a certain collection, and the other
68 for everything else, it might be necessary for a script to use two
69 different contexts to search both databases. Such scripts should use
70 the C<&set_context> and C<&restore_context> functions, below.
72 By default, C4::Context reads the configuration from
73 F</etc/koha.conf>. This may be overridden by setting the C<$KOHA_CONF>
74 environment variable to the pathname of a configuration file to use.
82 # In addition to what is said in the POD above, a Context object is a
83 # reference-to-hash with the following fields:
86 # A reference-to-hash whose keys and values are the
87 # configuration variables and values specified in the config
88 # file (/etc/koha.conf).
90 # A handle to the appropriate database for this context.
92 # Used by &set_dbh and &restore_dbh to hold other database
93 # handles for this context.
95 use constant CONFIG_FNAME => "/etc/koha.conf";
96 # Default config file, if none is specified
98 $context = undef; # Initially, no context is set
99 @context_stack = (); # Initially, no saved contexts
102 # Reads the specified Koha config file. Returns a reference-to-hash
103 # whose keys are the configuration variables, and whose values are the
104 # configuration values (duh).
105 # Returns undef in case of error.
108 # 2004-08-10 A. Tarallo: Added code that checks if a variable was already
109 # assigned and prints a message, otherwise create a new entry in the hash to
111 # Also added code that complaints if finds a line that isn't a variable
112 # assignmet and skips the line.
113 # Added a quick hack that makes the trasnlation between the db_schema
114 # and the DBI driver for that eschema.
118 my $fname = shift; # Config file to read
119 my $retval = {}; # Return value: ref-to-hash holding the
122 open (CONF, $fname) or return undef;
126 my $var; # Variable name
127 my $value; # Variable value
130 s/#.*//; # Strip comments
131 next if /^\s*$/; # Ignore blank lines
133 # Look for a line of the form
135 if (!/^\s*(\w+)\s*=\s*(.*?)\s*$/)
138 "$_ isn't a variable assignment, skipping it";
142 # Found a variable assignment
143 if ( exists $retval->{$1} )
145 print STDERR "$var was already defined, ignoring\n";
147 # Quick hack for allowing databases name in full text
148 if ( $1 eq "db_scheme" )
150 $value = db_scheme2dbi($2);
155 $retval->{$var} = $value;
164 # Translates the full text name of a database into de appropiate dbi name
171 if (/MySQL|mysql/) { return("mysql"); }
172 if (/Postgres|Pg|PostgresSQL/) { return("Pg"); }
173 if (/Oracle|oracle|ORACLE/) { return("Oracle"); }
175 return undef; # Just in case
181 my $conf_fname = shift; # Config file name
184 # Create a new context from the given config file name, if
185 # any, then set it as the current context.
186 $context = new C4::Context($conf_fname);
187 return undef if !defined($context);
188 $context->set_context;
193 $context = new C4::Context;
194 $context = new C4::Context("/path/to/koha.conf");
196 Allocates a new context. Initializes the context from the specified
197 file, which defaults to either the file given by the C<$KOHA_CONF>
198 environment variable, or F</etc/koha.conf>.
200 C<&new> does not set this context as the new default context; for
201 that, use C<&set_context>.
206 # 2004-08-10 A. Tarallo: Added check if the conf file is not empty
210 my $conf_fname = shift; # Config file to load
213 # check that the specified config file exists and is not empty
214 undef $conf_fname unless
215 (defined $conf_fname && -e $conf_fname && -s $conf_fname);
216 # Figure out a good config file to load if none was specified.
217 if (!defined($conf_fname))
219 # If the $KOHA_CONF environment variable is set, use
220 # that. Otherwise, use the built-in default.
221 $conf_fname = $ENV{"KOHA_CONF"} ||
224 $self->{"config_file"} = $conf_fname;
226 # Load the desired config file.
227 $self->{"config"} = &read_config_file($conf_fname);
228 return undef if !defined($self->{"config"});
230 $self->{"dbh"} = undef; # Database handle
231 $self->{"stopwords"} = undef; # stopwords list
239 $context = new C4::Context;
240 $context->set_context();
242 set_context C4::Context $context;
245 restore_context C4::Context;
247 In some cases, it might be necessary for a script to use multiple
248 contexts. C<&set_context> saves the current context on a stack, then
249 sets the context to C<$context>, which will be used in future
250 operations. To restore the previous context, use C<&restore_context>.
257 my $new_context; # The context to set
259 # Figure out whether this is a class or instance method call.
261 # We're going to make the assumption that control got here
262 # through valid means, i.e., that the caller used an instance
263 # or class method call, and that control got here through the
264 # usual inheritance mechanisms. The caller can, of course,
265 # break this assumption by playing silly buggers, but that's
266 # harder to do than doing it properly, and harder to check
268 if (ref($self) eq "")
270 # Class method. The new context is the next argument.
271 $new_context = shift;
273 # Instance method. The new context is $self.
274 $new_context = $self;
277 # Save the old context, if any, on the stack
278 push @context_stack, $context if defined($context);
280 # Set the new context
281 $context = $new_context;
284 =item restore_context
288 Restores the context set by C<&set_context>.
296 if ($#context_stack < 0)
299 die "Context stack underflow";
302 # Pop the old context and set it.
303 $context = pop @context_stack;
305 # FIXME - Should this return something, like maybe the context
306 # that was current when this was called?
311 $value = C4::Context->config("config_variable");
313 $value = C4::Context->config_variable;
315 Returns the value of a variable specified in the configuration file
316 from which the current context was created.
318 The second form is more compact, but of course may conflict with
319 method names. If there is a configuration variable called "new", then
320 C<C4::Config-E<gt>new> will not return it.
327 my $var = shift; # The config variable to return
329 return undef if !defined($context->{"config"});
330 # Presumably $self->{config} might be
331 # undefined if the config file given to &new
332 # didn't exist, and the caller didn't bother
333 # to check the return value.
335 # Return the value of the requested config variable
336 return $context->{"config"}{$var};
341 $sys_preference = C4::Context->preference("some_variable");
343 Looks up the value of the given system preference in the
344 systempreferences table of the Koha database, and returns it. If the
345 variable is not set, or in case of error, returns the undefined value.
349 # FIXME - The preferences aren't likely to change over the lifetime of
350 # the script (and things might break if they did change), so perhaps
351 # this function should cache the results it finds.
355 my $var = shift; # The system preference to return
356 my $retval; # Return value
357 my $dbh = C4::Context->dbh; # Database handle
358 my $sth; # Database query handle
360 # Look up systempreferences.variable==$var
361 $retval = $dbh->selectrow_array(<<EOT);
363 FROM systempreferences
364 WHERE variable='$var'
370 sub boolean_preference ($) {
372 my $var = shift; # The system preference to return
373 my $it = preference($self, $var);
374 return defined($it)? C4::Boolean::true_p($it): undef;
378 # This implements C4::Config->foo, and simply returns
379 # C4::Context->config("foo"), as described in the documentation for
382 # FIXME - Perhaps this should be extended to check &config first, and
383 # then &preference if that fails. OTOH, AUTOLOAD could lead to crappy
384 # code, so it'd probably be best to delete it altogether so as not to
385 # encourage people to use it.
390 $AUTOLOAD =~ s/.*:://; # Chop off the package name,
391 # leaving only the function name.
392 return $self->config($AUTOLOAD);
396 # Internal helper function (not a method!). This creates a new
397 # database connection from the data given in the current context, and
401 my $db_driver = $context->{"config"}{"db_scheme"} || "mysql";
402 # FIXME - It should be possible to use "MySQL" instead
403 # of "mysql", "PostgreSQL" instead of "Pg", and so
405 my $db_name = $context->{"config"}{"database"};
406 my $db_host = $context->{"config"}{"hostname"};
407 my $db_user = $context->{"config"}{"user"};
408 my $db_passwd = $context->{"config"}{"pass"};
409 return DBI->connect("DBI:$db_driver:$db_name:$db_host",
410 $db_user, $db_passwd);
415 $dbh = C4::Context->dbh;
417 Returns a database handle connected to the Koha database for the
418 current context. If no connection has yet been made, this method
419 creates one, and connects to the database.
421 This database handle is cached for future use: if you call
422 C<C4::Context-E<gt>dbh> twice, you will get the same handle both
423 times. If you need a second database handle, use C<&new_dbh> and
424 possibly C<&set_dbh>.
432 # If there's already a database handle, return it.
433 return $context->{"dbh"} if defined($context->{"dbh"});
435 # No database handle yet. Create one.
436 $context->{"dbh"} = &_new_dbh();
438 return $context->{"dbh"};
443 $dbh = C4::Context->new_dbh;
445 Creates a new connection to the Koha database for the current context,
446 and returns the database handle (a C<DBI::db> object).
448 The handle is not saved anywhere: this method is strictly a
449 convenience function; the point is that it knows which database to
450 connect to so that the caller doesn't have to know.
463 $my_dbh = C4::Connect->new_dbh;
464 C4::Connect->set_dbh($my_dbh);
466 C4::Connect->restore_dbh;
468 C<&set_dbh> and C<&restore_dbh> work in a manner analogous to
469 C<&set_context> and C<&restore_context>.
471 C<&set_dbh> saves the current database handle on a stack, then sets
472 the current database handle to C<$my_dbh>.
474 C<$my_dbh> is assumed to be a good database handle.
483 # Save the current database handle on the handle stack.
484 # We assume that $new_dbh is all good: if the caller wants to
485 # screw himself by passing an invalid handle, that's fine by
487 push @{$context->{"dbh_stack"}}, $context->{"dbh"};
488 $context->{"dbh"} = $new_dbh;
493 C4::Context->restore_dbh;
495 Restores the database handle saved by an earlier call to
496 C<C4::Context-E<gt>set_dbh>.
504 if ($#{$context->{"dbh_stack"}} < 0)
507 die "DBH stack underflow";
510 # Pop the old database handle and set it.
511 $context->{"dbh"} = pop @{$context->{"dbh_stack"}};
513 # FIXME - If it is determined that restore_context should
514 # return something, then this function should, too.
519 $dbh = C4::Context->stopwords;
521 Returns a hash with stopwords.
523 This hash is cached for future use: if you call
524 C<C4::Context-E<gt>stopwords> twice, you will get the same hash without real DB access
532 # If the hash already exists, return it.
533 return $context->{"stopwords"} if defined($context->{"stopwords"});
535 # No hash. Create one.
536 $context->{"stopwords"} = &_new_stopwords();
538 return $context->{"stopwords"};
542 # Internal helper function (not a method!). This creates a new
543 # hash with stopwords
546 my $dbh = C4::Context->dbh;
548 my $sth = $dbh->prepare("select word from stopwords");
550 while (my $stopword = $sth->fetchrow_array) {
552 $stopwordlist->{$stopword} = uc($stopword);
554 return $stopwordlist;
568 Specifies the configuration file to read.
578 Andrew Arensburger <arensb at ooblick dot com>