- NAME
- SYNOPSYS
- DESCRIPTION
  - %META
- METHODS
  - new
  - LoadConfigs
- LoadConfig
  - Configs
  - LoadedConfigs
  - Get
  - GetObfuscated
  - Set
  - Metadata
  - Meta
  - AddOption( Name => '', Section => '', ... )
  - DeleteOption( Name => '' )
  - UpdateOption( Name => '' ), Section => '', ... )

# NAME

        RT::Config - RT's config

# SYNOPSYS

        # get config object
        use RT::Config;
        my $config = RT::Config->new;
        $config->LoadConfigs;

        # get or set option
        my $rt_web_path = $config->Get('WebPath');
        $config->Set(EmailOutputEncoding => 'latin1');

        # get config object from RT package
        use RT;
        RT->LoadConfig;
        my $config = RT->Config;

# DESCRIPTION

`RT::Config` class provide access to RT's and RT extensions' config files.

RT uses two files for site configuring:

First file is RT_Config.pm - core config file. This file is shipped with RT distribution and contains default values for all available options. You should never edit this file.

Second file is RT_SiteConfig.pm - site config file. You can use it to customize your RT instance. In this file you can override any option listed in core config file.

RT extensions could also provide thier config files. Extensions should use <NAME>_Config.pm and <NAME>_SiteConfig.pm names for config files, where <NAME> is extension name.

NOTE: All options from RT's config and extensions' configs are saved in one place and thus extension could override RT's options, but it is not recommended.

## %META

Hash of Config options that may be user overridable or may require more logic than should live in RT_*Config.pm

Keyed by config name, there are several properties that can be set for each config optin:

     Section     - What header this option should be grouped
                   under on the user Preferences page
     Overridable - Can users change this option
     SortOrder   - Within a Section, how should the options be sorted
                   for display to the user
     Widget      - Mason component path to widget that should be used
                   to display this config option
     WidgetArguments - An argument hash passed to the WIdget
        Description - Friendly description to show the user
        Values      - Arrayref of options (for select Widget)
        ValuesLabel - Hashref, key is the Value from the Values
                      list, value is a user friendly description
                      of the value
        Callback    - subref that receives no arguments.  It returns
                      a hashref of items that are added to the rest
                      of the WidgetArguments
     PostSet       - subref passed the RT::Config object and the current and
                     previous setting of the config option.  This is called well
                     before much of RT's subsystems are initialized, so what you
                     can do here is pretty limited.  It's mostly useful for
                     effecting the value of other config options early.
     PostLoadCheck - subref passed the RT::Config object and the current
                     setting of the config option.  Can make further checks
                     (such as seeing if a library is installed) and then change
                     the setting of this or other options in the Config using
                     the RT::Config option.
       Obfuscate   - subref passed the RT::Config object, current setting of the config option
                     and a user object, can return obfuscated value. it's called in
                     RT->Config->GetObfuscated()

# METHODS

## new

Object constructor returns new object. Takes no arguments.

## LoadConfigs

Load all configs. First of all load RT's config then load extensions' config files in alphabetical order. Takes no arguments.

# LoadConfig

Takes param hash with `File` field. First, the site configuration file is loaded, in order to establish overall site settings like hostname and name of RT instance. Then, the core configuration file is loaded to set fallback values for all settings; it bases some values on settings from the site configuration file.

Note that core config file don't change options if site config has set them so to add value to some option instead of overriding you have to copy original value from core config file.

## Configs

Returns list of config files found in local etc, plugins' etc and main etc directories.

## LoadedConfigs

Returns a list of hashrefs, one for each config file loaded. The keys of the hashes are:

as

  Name this config file was loaded as (relative filename usually).

filename

  The full path and filename.

extension

  The "extension" part of the filename. For example, the file `RTIR_Config.pm` will have an `extension` value of `RTIR`.

site

  True if the file is considered a site-level override. For example, `site` will be false for `RT_Config.pm` and true for `RT_SiteConfig.pm`.

## Get

Takes name of the option as argument and returns its current value.

In the case of a user-overridable option, first checks the user's preferences before looking for site-wide configuration.

Returns values from RT_SiteConfig, RT_Config and then the %META hash of configuration variables's "Default" for this config variable, in that order.

Returns different things in scalar and array contexts. For scalar options it's not that important, however for arrays and hash it's. In scalar context returns references to arrays and hashes.

Use `scalar` perl's op to force context, especially when you use `(..., Argument =` RT->Config->Get('ArrayOpt'), ...)> as perl's '=>' op doesn't change context of the right hand argument to scalar. Instead use `(..., Argument =` scalar RT->Config->Get('ArrayOpt'), ...)>.

It's also important for options that have no default value(no default in etc/RT_Config.pm). If you don't force scalar context then you'll get empty list and all your named args will be messed up. For example `(arg1 =` 1, arg2 => RT->Config->Get('OptionDoesNotExist'), arg3 => 3)> will result in `(arg1 =` 1, arg2 => 'arg3', 3)> what is most probably unexpected, or `(arg1 =` 1, arg2 => RT->Config->Get('ArrayOption'), arg3 => 3)> will result in `(arg1 =` 1, arg2 => 'element of option', 'another_one' => ..., 'arg3', 3)>.

## GetObfuscated

the same as Get, except it returns Obfuscated value via Obfuscate sub

## Set

Set option's value to new value. Takes name of the option and new value. Returns old value.

The new value should be scalar, array or hash depending on type of the option. If the option is not defined in meta or the default RT config then it is of scalar type.

## Metadata

## Meta

## AddOption( Name => '', Section => '', ... )

## DeleteOption( Name => '' )

## UpdateOption( Name => '' ), Section => '', ... )

← Back to index