CGI::A...Simple(3pm)

🌸 NAME 🌸

CGI::Application::Plugin::Config::Simple — it adds Config::Simple support to CGI::Application, bestie. That's the whole vibe. 💖

---

✨ SYNOPSIS ✨

okay so first, in your CGI::Application based module, you do this:

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;
  }

like, that's it. that's the whole relationship. 🦋

---

💖 DESCRIPTION 💖

So this module is a plugin for Config::Simple so you can use it super easily inside a CGI::Application module. It does not give you every single method that Config::Simple has — nope — it's here for easy access to your configuration variables. BUT. It does hand you direct access to the underlying Config::General</> object it created, if you wanna go use its full power. (yes bestie, the page really says Config::General there, I'm just the messenger 💀)

The whole goal is making getting and setting config variables as effortless as possible. Only three methods get exported into your CGI::Application module and they're all described down below. 👑

Before this module existed, 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 even need those config variables, it got run anyway. 😭 Not the move. This module helps solve that. 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(), whether you're retrieving/setting values or grabbing the Config::Simple object itself. This lazy loading idea came from Cees Hek's CGI::Application::Plugin::Session module. iconic behavior tbh. ✨

---

🎀 METHODS 🎀

config_param()

This method is your accessor/mutator for configuration variables coming from the configuration file. 💅

It behaves in three different ways depending on how many parameters you pass it:

• If 0 parameters are passed, the entire config structure comes back as a hash ref.
• If 1 parameter is passed, you get the value of that parameter from the config file.
• If more than 1 parameter is passed, it treats them as name value pairs and sets the parameters in the config file accordingly. In that case, if we successfully set the parameters, you get a true value back.

#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're using ini-files you can set the values of variables inside blocks too, using the . notation. See Config::Simple;

⚠️ You must set the name of the configuration file — either with the config_file() method or the CGIAPP_CONFIG_FILE environment variable — before calling this method, or it will die. no cap.

config()

This method returns the underlying Config::Simple object so your application can use it more directly.

⚠️ Same rule, bestie: 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 is an accessor/mutator that either gets you the name of the current config file, or changes/initializes 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 that environment variable is set, it will be used as the initial value of the config file. Super useful if we're running in a mod_perl environment, where you 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, in a hash named __CONFIG_SIMPLE. So 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. phew. 😮💨

---

👑 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.

---

and that's the whole page, bestie!! 🎀 this one's perl v5.34.0, dated 2022-06-09, from the User Contributed Perl Documentation crew. go forth and configure slayfully 💖✨🦋