view release on metacpan or  search on metacpan

lib/Dancer2/Manual/Config.pod  view on Meta::CPAN

package Dancer2::Config;
# ABSTRACT: Dancer2 Configuration Reference

__END__

=pod

=encoding UTF-8

=head1 NAME

Dancer2::Config - Dancer2 Configuration Reference

=head1 VERSION

version 2.1.0

=head1 DESCRIPTION

The Dancer2 default configuration system (as implemented by
L<Dancer2::ConfigReader::Config::Any>) handles reading and changing the
configuration of your Dancer2 apps.  This document describes how to
manipulate Dancer2's configuration settings (through code or by file), and
to document the various settings that are available in Dancer2.

=head1 MANIPULATING SETTINGS VIA CODE

You can change a setting with the keyword C<set>:

    use Dancer2;

    # changing default settings
    set port         => 8080;
    set content_type => 'text/plain';
    set startup_info => 0;

=head1 MANIPULATING SETTINGS VIA CONFIGURATION FILES

There's nothing wrong with using C<set> to configure your application.  In
fact you might have some great reasons for doing so.  For greater
flexibility, ease of deployment, etc., you should also consider extracting
those settings into a configuration file.

=head2 Configuration file path and file names

Dancer2 will first look for the file F<config.EXT> (where F<EXT> is the
type of configuration file you are using; e.g. F<ini> or F<json> or
F<yml>) in the root directory of your application. This is considered
your global Dancer2 config file. If you do not care to have separate
settings for production and development environments (B<not> a
recommended practice!), then this file is all you need.

Next, Dancer2 will look for a file called F<config_local.EXT>. This file
is typically useful for deployment-specific configuration that should
not be checked into source control. For instance, database credentials
could be stored in this file.  Any settings in this file are merged into
the existing configuration such that those with the same name in your
local configuration file will take precedence over those settings in
the global file.

Next, Dancer2 will look in the F<environments> directory for a configuration
file specific to the platform you are deploying to (F<production.EXT> or
F<development.EXT>, for example).  Again, the configuration from the environment
is merged with the existing configuration with the deployment config taking
precedence.

Finally, Dancer2 will look in the F<environments> directory for a
local configuration for the specific platform you are deploying to
(e.g. F<production_local.EXT> or F<development_local.EXT>)
The configuration in this file is merged as before.

Much like F<config_local.EXT>, this file would be useful for environment-
specific configuration that would not be checked into source control.
For instance, when developing an application that talks to multiple services,
each developer could have their own URLs to those services stored within
their F<environments/development_local.yaml> file.

Note, if there is no F<config.EXT>, Dancer2 will not look for a
F<config_local.EXT>. The same is true for the local environment
configuration.

=head2 Supported configuration file formats

Dancer2 supports any configuration file format that is supported by
L<Config::Any>.  At the time of this writing, that includes YAML (.yml and
.yaml), JSON (.jsn and .json), INI (.ini), Apache-style configurations (.cnf
and .conf), XML (.xml), and Perl-style hashes (.pl and .perl).

Dancer2 iterates over these file extensions in the order provided by
L<Config::Any> and loads any config files that it finds with later
configuration information overriding earlier config information. To
restrict which file extension Dancer2 looks for, you may set the
C<DANCER_CONFIG_EXT> envinroment variable to a specific extension and
Dancer2 will only look for config files with that extension.

Make sure you pick the appropriate extension for your configuration file
name, as Dancer2 guesses the type of format based on the file extension.

=head2 Sample configuration files

Note: Not all possibilities are covered here, only the most common options.

If you prefer YAML, a sample YAML based config file might look like this:

    appname: "Hello"
    charset: "UTF-8"
    auto_page: 1

    session: "YAML"
    serializer: "JSON"

    plugins:
      DBIC:
        default:
          dsn: dbi:SQLite:db/mydata.db