Cataly...Manual(3pm)

💖 NAME 💖

Catalyst::Plugin::ConfigLoader::Manual — the ✨ guide ✨ to using the ConfigLoader plugin, bestie. That's it, that's the whole name, and it's literally the roadmap for everything below.

---

🎀 BASIC USAGE 🎀

okay so first things first, you gotta actually turn the plugin on. It's giving "two lines and you're iconic":

package MyApp;

use Catalyst qw( ConfigLoader ... );

that's the whole vibe check. Load it in your Catalyst app and the config magic just... happens. periodt. 🦋

---

🌸 ENVIRONMENT VARIABLES 🌸

These are the little gremlins that control which config files get loaded. Lowkey the most powerful part of this whole thing, ngl:

• MYAPP_CONFIG — the specific config file to load for MyApp 👑
• CATALYST_CONFIG_LOCAL_SUFFIX — a global suffix for extra config files 🌈
• MYAPP_CONFIG_LOCAL_SUFFIX — a suffix that's specifically for MyApp 💅

---

✨ CONFIG FORMATS ✨

Not me having SO many format options for you. Pick your fave, they all slay. 💖

🍓 Config::General

### Extensions

• cnf
• conf

### Example Config

name = TestApp
<Component Controller::Foo>
    foo bar
</Component>
<Model Baz>
    qux xyzzy
</Model>

---

🧚 INI

### Extensions

• ini

### Example Config

name=TestApp

[Controller::Foo]
foo=bar

[Model::Baz]
qux=xyzzy

---

🦋 JSON

### Extensions

• jsn
• json

### Example Config

{
    "name": "TestApp",
    "Controller::Foo": {
        "foo": "bar"
    },
    "Model::Baz": {
        "qux": "xyzzy"
    }
}

---

💜 Perl

### Extensions

• pl
• perl

### Example Config

{
    name => 'TestApp',
    'Controller::Foo' => {
        foo => 'bar'
    },
    'Model::Baz' => {
        qux => 'xyzzy'
    }
}

---

👑 XML

### Extensions

• xml

### Example Config

<config>
    <name>MyApp::CMS</name>
    <paths>
        <upload_dir>/var/www/docs/myapp-cms/uploads</upload_dir>
    </paths>
    <model name="DB">
        <connect_info>dbi:mysql:cmsdb</connect_info>
        <connect_info>user</connect_info>
        <connect_info>password</connect_info>
    </model>
    <component name="View::TT">
        <INCLUDE_PATH>__path_to(root,templates)__</INCLUDE_PATH>
        <ENCODING>UTF-8</ENCODING>
        <TRIM>1</TRIM>
        <PRE_CHOMP>2</PRE_CHOMP>
        <POST_CHOMP>2</POST_CHOMP>
    </component>
</config>

🚨 okay IMPORTANT bestie, listen up: the name attribute on the model tag has to be the relative namespace of your Catalyst model, not the absolute one. So for MyApp::Model::Something, the name attribute should just be Something. Don't come for me, that's literally how it works. 😭

---

🌈 YAML

### Extensions

• yml
• yaml

### Example Config

---
name: TestApp
Controller::Foo:
    foo: bar
Model::Baz:
    qux: xyzzy

---

🔥 COOKBOOK 🔥

Recipes, bestie. Little how-tos. We love a practical queen. 🫶

💅 Configuring a Catalyst::Model::DBIC::Schema model from a YAML config

Model::MyModel:
    schema_class: MyApp::MySchema
    connect_info:
        - dbi:SQLite:myapp.db
        - ''
        - ''
        - AutoCommit: 1

---

⭐ Converting your existing config to Config::General format

So as of Catalyst::Devel 1.07, a freshly created application uses Config::General for its configuration. If you wanna convert your existing config over, run this one-liner (just swap MyApp for your app's actual name, iykyk):

perl -Ilib -MMyApp -MConfig::General -e 'Config::General->new->save_file("myapp.conf", MyApp->config);'

---

🌸 Using UTF-8 strings in a Config::General file

Got UTF-8 strings chillin' in your Config::General-based config file? Then you should add this config info to MyApp.pm, no cap:

__PACKAGE__->config( 'Plugin::ConfigLoader' => {
    driver => {
        'General' => { -UTF8 => 1 },
    }
} );

---

🦋 Using a local configuration file

When ConfigLoader reads configurations, it starts by reading the configuration file for myapp with one of the supported extensions listed up above. 👆

For example, a Config::General config file is myapp.conf.

If a configuration file called myapp_local exists with one of the supported file extensions, it gets read too, and the values from that file override the values from the main config file. 💥

A Config::General local configuration file would be called myapp_local.conf.

And guess what — the local suffix can be changed! See get_config_local_suffix in Catalyst::Plugin::ConfigLoader for the details of how. 💫

This is useful because it lets different people or environments have different configuration files. Like, picture a project with three developers — Tom, Dick, and Harry — plus a production environment. That project can have a myapp_tom.conf, a myapp_dick.conf, a myapp_harry.conf, and a myapp_production.conf. Everyone gets their own, so cute. 🎀

Each developer, and the web server, would set the environment variable to load their proper configuration file. And all of the configurations can be stored properly in source control. Iconic, honestly.

😭 but heads up: if there's no myapp_local.ext (where .ext is a supported extension), and the individual configuration files contain something required to start the application — like the Model's data source definition — then the application won't start unless the environment variable is set properly. So like... set it. Please. 🙈

---

and that's the whole page, bestie! 💖 this gem was written by the User Contributed Perl Documentation crew, running on perl v5.30.3, dated 2020-07-30. go forth and configure, you absolute main character. slay. 💅✨🦋