C4::Context - Maintain and manipulate the context of a Koha script
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;
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.
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.
$context = C4::Context->new;
$context = C4::Context->new("/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.
It saves the koha-conf.xml values in the declared memcached server(s) if currently available and uses those values until them expire and re-reads them.
&new does not set this context as the new default context; for that, use &set_context.
$context = new C4::Context; $context->set_context(); or set_context C4::Context $context;
$value = C4::Context->config("config_variable");
Returns the value of a variable specified in the configuration file from which the current context was created.
$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.
Retrieves the required system preference value, and converts it from YAML into a Perl data structure. It throws an exception if the value cannot be properly decoded as YAML.
Retrieves the required system preference value, and splits it into pieces using the pipe (|) symbol as separator.
C4::Context->enable_syspref_cache();
Enable the in-memory syspref cache used by C4::Context. This is the default behavior.
C4::Context->disable_syspref_cache();
Disable the in-memory syspref cache used by C4::Context. This should be used with Plack and other persistent environments.
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.
C4::Context->set_preference( $variable, $value, [ $explanation, $type, $options ] );
This updates a preference's value both in the systempreferences table and in the sysprefs cache. If the optional parameters are provided, then the query becomes a create. It won't update the parameters (except value) for an existing preference.
C4::Context->delete_preference( $variable );
This deletes a system preference from the database. Returns a true value on success. Failure means there was an issue with the database, not that there was no syspref of the name.
$delimiter = C4::Context->csv_delimiter;
Returns preferred CSV delimiter, using system preference 'CSVDelimiter'.
If this preference is missing or empty, comma will be returned.
This method is needed because of special behavior for tabulation.
You can, optionally, pass a value parameter to this routine
in the case of existing delimiter.
$delimiter = C4::Context->default_catalog_sort_by;
Returns default sort by for catalog search.
For relevance no sort order is used.
For staff interface, depends on system preferences 'defaultSortField' and 'defaultSortOrder'.
For OPAC interface, depends on system preferences 'OPACdefaultSortField' and 'OPACdefaultSortOrder'.
$Zconn = C4::Context->Zconn
Returns a connection to the Zebra database
$self
$server one of the servers defined in the koha-conf.xml file
$async whether this is a asynchronous connection
$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 = 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.
$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.
C4::Context->userenv;
Retrieves a hash for user environment variables.
C4::Context->set_userenv($usernum, $userid, $usercnum,
$userfirstname, $usersurname,
$userbranch, $branchname, $userflags,
$emailaddress, $shibboleth
$desk_id, $desk_name,
$register_id, $register_name);
Establish a hash of user environment variables.
set_userenv is called in Auth.pm
C4::Context->unset_userenv;
Destroys user environment variables.
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'.
C4::Context->tz Returns a DateTime::TimeZone object for the system timezone
C4::Context->IsSuperLibrarian();
Sets the current interface for later retrieval in any Perl module
C4::Context->interface('opac');
C4::Context->interface('intranet');
my $interface = C4::Context->interface;
my $test = C4::Context->only_my_library;
Returns true if you enabled IndependentBranches and the current user
does not have superlibrarian permissions.
Returns root directory for temporary storage
set_remote_address should be called at the beginning of every script that is *not* running under plack in order to the REMOTE_ADDR environment variable to be set correctly.
https_enabled should be called when checking if a HTTPS connection is used.
Note that this depends on a HTTPS environmental variable being defined by the web server. This function may not return the expected result, if your web server or reverse proxies are not setting the correct X-Forwarded-Proto headers and HTTPS environmental variable.
Note too that the HTTPS value can vary from web server to web server. We are relying on the convention of the value being "on" or "ON" here.
if ( $context->needs_install ) { ... }
This method returns a boolean representing the install status of the Koha instance.
psgi_env returns true if there is an environmental variable prefixed with "psgi" or "plack". This is useful for detecting whether this is a PSGI app or a CGI app, and implementing code as appropriate.
is_internal_PSGI_request is used to detect if this request was made from within the individual PSGI app or externally from the mounted PSGI app
KOHA_CONFSpecifies the configuration file to read.
Andrew Arensburger <arensb at ooblick dot com>
Joshua Ferraro <jmf at liblime dot com>