<<

NAME

C4::Context - Maintain and manipulate the context of a Koha script

SYNOPSIS

  use C4::Context;

  use C4::Context("/path/to/koha-conf.xml");

  $config_value = C4::Context->config("config_variable");

  $koha_preference = C4::Context->preference("preference");

  $db_handle = C4::Context->dbh;

  $Zconn = C4::Context->Zconn;

  $stopwordhash = C4::Context->stopwords;

DESCRIPTION

When a Koha script runs, it makes use of a certain number of things: configuration settings in /etc/koha/koha-conf.xml, a connection to the Koha databases, and so forth. These things make up the context in which the script runs.

This module takes care of setting up the context for a script: figuring out which configuration file to load, and loading it, opening a connection to the right database, and so forth.

Most scripts will only use one context. They can simply have

  use C4::Context;

at the top.

Other scripts may need to use several contexts. For instance, if a library has two databases, one for a certain collection, and the other for everything else, it might be necessary for a script to use two different contexts to search both databases. Such scripts should use the &set_context and &restore_context functions, below.

By default, C4::Context reads the configuration from /etc/koha/koha-conf.xml. This may be overridden by setting the $KOHA_CONF environment variable to the pathname of a configuration file to use.

METHODS

KOHAVERSION returns the kohaversion stored in kohaversion.pl file
read_config_file

Reads the specified Koha config file.

Returns an object containing the configuration variables. The object's structure is a bit complex to the uninitiated ... take a look at the koha-conf.xml file as well as the XML::Simple documentation for details. Or, here are a few examples that may give you what you need:

The simple elements nested within the <config> element:

    my $pass = $koha->{'config'}->{'pass'};

The <listen> elements:

    my $listen = $koha->{'listen'}->{'biblioserver'}->{'content'};

The elements nested within the <server> element:

    my $ccl2rpn = $koha->{'server'}->{'biblioserver'}->{'cql2rpn'};

Returns undef in case of error.

new
  $context = new C4::Context;
  $context = new C4::Context("/path/to/koha-conf.xml");

Allocates a new context. Initializes the context from the specified file, which defaults to either the file given by the $KOHA_CONF environment variable, or /etc/koha/koha-conf.xml.

&new does not set this context as the new default context; for that, use &set_context.

set_context
  $context = new C4::Context;
  $context->set_context();
or
  set_context C4::Context $context;

  ...
  restore_context C4::Context;

In some cases, it might be necessary for a script to use multiple contexts. &set_context saves the current context on a stack, then sets the context to $context, which will be used in future operations. To restore the previous context, use &restore_context.

restore_context
  &restore_context;

Restores the context set by &set_context.

config
  $value = C4::Context->config("config_variable");

  $value = C4::Context->config_variable;

Returns the value of a variable specified in the configuration file from which the current context was created.

The second form is more compact, but of course may conflict with method names. If there is a configuration variable called "new", then C4::Config->new will not return it.

preference
  $sys_preference = C4::Context->preference('some_variable');

Looks up the value of the given system preference in the systempreferences table of the Koha database, and returns it. If the variable is not set or does not exist, undef is returned.

In case of an error, this may return 0.

Note: It is impossible to tell the difference between system preferences which do not exist, and those whose values are set to NULL with this method.

clear_syspref_cache
  C4::Context->clear_syspref_cache();

  cleans the internal cache of sysprefs. Please call this method if
  you update the systempreferences table. Otherwise, your new changes
  will not be seen by this process.
Zconn

$Zconn = C4::Context->Zconn

Returns a connection to the Zebra database for the current context. If no connection has yet been made, this method creates one and connects.

$self

$server one of the servers defined in the koha-conf.xml file

$async whether this is a asynchronous connection

$auth whether this connection has rw access (1) or just r access (0 or NULL)

_new_Zconn

$context->{"Zconn"} = &_new_Zconn($server,$async);

Internal function. Creates a new database connection from the data given in the current context and returns it.

$server one of the servers defined in the koha-conf.xml file

$async whether this is a asynchronous connection

$auth whether this connection has rw access (1) or just r access (0 or NULL)

dbh
  $dbh = C4::Context->dbh;

Returns a database handle connected to the Koha database for the current context. If no connection has yet been made, this method creates one, and connects to the database.

This database handle is cached for future use: if you call C4::Context->dbh twice, you will get the same handle both times. If you need a second database handle, use &new_dbh and possibly &set_dbh.

new_dbh
  $dbh = C4::Context->new_dbh;

Creates a new connection to the Koha database for the current context, and returns the database handle (a DBI::db object).

The handle is not saved anywhere: this method is strictly a convenience function; the point is that it knows which database to connect to so that the caller doesn't have to know.

set_dbh
  $my_dbh = C4::Connect->new_dbh;
  C4::Connect->set_dbh($my_dbh);
  ...
  C4::Connect->restore_dbh;

&set_dbh and &restore_dbh work in a manner analogous to &set_context and &restore_context.

&set_dbh saves the current database handle on a stack, then sets the current database handle to $my_dbh.

$my_dbh is assumed to be a good database handle.

restore_dbh
  C4::Context->restore_dbh;

Restores the database handle saved by an earlier call to C4::Context->set_dbh.

marcfromkohafield
  $dbh = C4::Context->marcfromkohafield;

Returns a hash with marcfromkohafield.

This hash is cached for future use: if you call C4::Context->marcfromkohafield twice, you will get the same hash without real DB access

stopwords
  $dbh = C4::Context->stopwords;

Returns a hash with stopwords.

This hash is cached for future use: if you call C4::Context->stopwords twice, you will get the same hash without real DB access

userenv
  C4::Context->userenv;

Retrieves a hash for user environment variables.

This hash shall be cached for future use: if you call C4::Context->userenv twice, you will get the same hash without real DB access

set_userenv
  C4::Context->set_userenv($usernum, $userid, $usercnum, $userfirstname, $usersurname, $userbranch, $userflags, $emailaddress);

Establish a hash of user environment variables.

set_userenv is called in Auth.pm

_new_userenv
  C4::Context->_new_userenv($session);  # FIXME: This calling style is wrong for what looks like an _internal function

Builds a hash for user environment variables.

This hash shall be cached for future use: if you call C4::Context->userenv twice, you will get the same hash without real DB access

_new_userenv is called in Auth.pm

_unset_userenv
  C4::Context->_unset_userenv;

Destroys the hash for activeuser user environment variables.

get_versions
  C4::Context->get_versions

Gets various version info, for core Koha packages, Currently called from carp handle_errors() sub, to send to browser if 'DebugLevel' syspref is set to '2'.

ENVIRONMENT

KOHA_CONF

Specifies the configuration file to read.

SEE ALSO

XML::Simple

AUTHORS

Andrew Arensburger <arensb at ooblick dot com>

Joshua Ferraro <jmf at liblime dot com>

<<