NAME¶
CGI::Application::Plugin::Config::Simple - Add Config::Simple support to
CGI::Application
SYNOPSIS¶
in your CGI::Application based module
use CGI::Application::Plugin::Config::Simple;
sub cgiapp_init {
my $self = shift;
#set my config file
$self->config_file('myapp.conf');
#
#do other stuff
#
}
#later on in a run mode
sub run_mode1 {
my $self = shift;
#just get a single parameter from my config file
my $value = $self->config_param('my_param');
#get a parameter in a block (if using ini style files)
$value = $self->config_param('my_block.my_param');
#the entire config hash reference
my $config_vars = $self->config_param();
#get my Config::Simple object for direct access
my $config = $self->config;
}
DESCRIPTION¶
This module acts as a plugin for Config::Simple to be easily used inside of a
CGI::Application module. It does not provide every method available from
Config::Simple but rather easy access to your configuration variables. It does
however provide direct access to the underlying Config::General object created
if you want to use it's full power.
The module tries to make the getting and setting of configuration variables as
easy as possible. Only three methods are exported into your CGI::Application
module and they are described below.
Before I wrote this module sometimes I would put my code that read in the
configuration file into the
cgiapp_init() or
cgiapp_prerun()
methods but then if I had a run mode that didn't need those config variables
it was run anyway. This module helps to solve this is. The Config::Simple
object is not created (and the config file is not read and parsed) until after
your first call to
config() or
config_param() to either
retrieve/set values, or get the Config::Simple object. This lazy loading idea
came from Cees Hek's CGI::Application::Plugin::Session module.
METHODS¶
config_param()¶
This method acts as an accessor/mutator for configuration variables coming from
the configuration file.
This method will behave in three different ways depending on how many parameters
it is passed. If 0 parameters are passed then the entire config structure will
be returned as a hash ref. If 1 parameters is passed then the value of that
parameter in the config file will be returned. If more than 1 parameter is
passed then it will treat them as name value pairs and will set the parameters
in the config file accordingly. In this case, if we successfully set the
parameters then a true value will be returned.
#get the complete config hash
my $config_hash = $self->config_param();
#just get one config value
my $value = $self->config_param($parameter);
#set multiple config values
my $success = $self->config_param(param1 => $value1, param2 => $value2);
This method uses Config::Simple so if you are using ini-files then you can set
the values of variables inside blocks as well using the '.' notation. See
Config::Simple;
You must set the name of the configuration file either using the
config_file() method or the CGIAPP_CONFIG_FILE environment variable
before calling this method or it will 'die'.
config()¶
This method will return the underlying Config::Simple object for more direct use
by your application. You must set the name of the configuration file either
using the
config_file() method or the CGIAPP_CONFIG_FILE environment
variable before calling this method or it will 'die'.
my $conf = $self->config();
config_file([$file_name])¶
This method acts as an accessor/mutator to either get the name of the current
config file or to change/initialize it. This method must be called to
initialize the name of the config file before any call can be made to either
config() or
config_param() unless the 'CGIAPP_CONFIG_FILE'
environment variable has been set. If this environment variable is set it will
be used as the initial value of the config file. This is useful if we are
running in a mod_perl environment when can use a statement like this in your
httpd.conf file:
PerlSetEnv CGIAPP_CONFIG_FILE /path/to/my/conf
It is typical to set the name of the config file in the
cgiapp_init()
phase of your application.
If a value is passed as a parameter then the config file with that name is used.
It will always return the name of the current config file.
#get the value of the CGIAPP_CONFIG_FILE environment variable (if there is one)
#since we haven't set the config file's name with config_file() yet.
my $file_name = $self->config_file();
#set the config file's name
$self->config_file('myapp.conf');
#get the name of the config file
$file_name = $self->config_file();
CAVEATS¶
The CGI::Application object is implemented as a hash and we store the variables
used by this module's methods inside of it as a hash named __CONFIG_SIMPLE. If
you use any other CGI::Application plugins there would be problems if they
also used $self->{__CONFIG_SIMPLE} but in practice this should never
actually happen.
AUTHOR¶
Michael Peters <mpeters@plusthree.com>
Thanks to Plus Three, LP (
http://www.plusthree.com) for sponsoring my work on
this module
SEE ALSO¶
- •
- CGI::Application
- •
- Config::Simple
LICENSE¶
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.