Configoro
Environment-specific configuration data for Rails apps
| Author | Tim Morgan | | License | Released under the MIT license. |
About
Pretty much every Rails app out there needs to store environment-specific
configuration data: API URLs, Memcache settings, AWS keys, etc. The "quick fix"
approach is usually to dump this information in, e.g., development.rb
as
constants, like MAILCHIMP_API_URL
. This creates cluttered and unorganized
environment files.
Configoro creates a configuration object that can be accessed as both a hash and struct. It stores common configuration data merged with environment-specific data.
The data is read from YAML files stored alongside the environment files.
Installation
To use this gem, simply add
gem 'configoro'
to your Gemfile, then run
rails generate configoro
to install some default configuration files. Edit these new files with your configuration data.
Usage
Assume your application namespace is MyApp
(which is what it
would be if you had created your Rails project using rails new my_app
). You
can find your namespace in your config/application.rb
file.
In this case, you would access your configuration using the
MyApp::Configuration
object. You can access it as an indifferent hash
MyApp::Configuration[:mailchimp_api_url]
MyApp::Configuration['mailchimp_api_url']
or as a struct.
MyApp::Configuration.mailchimp_api_url
If you include any hashes in your configuration YAML files, they will also be accessible as indifferent hashes or structs:
MyApp::Configuration.memcache.timeout
MyApp::Configuration[:memcache]['timeout']
MyApp::Configuration['memcache'].timeout
Configuration Files
Configuration is stored within the config/environments
directory of your Rails
app. Files ending in ".yml" are loaded from the common/
subdirectory and a
subdirectory named after the current environment.
Configuration files are preprocessed as ERB, in the same way that Rails
preprocesses config/database.yml
. This allows dynamic configuration,
e.g. host: <%= ENV["DB_HOST"] || "localhost" %>
.
Each file goes into its own hash in the configuration. For example, if you
placed a file called memcache.yml
within config/environments/development
,
you would be able to access your Memcache timeout using
MyApp::Configuration.memcache.timeout
.
h3. Custom Configuration Locations
If you need to do your own configuration loading, you can do so using the
{Configoro::Hash#<<} method. For example, you could place the following in a
Ruby file under config/initializers
:
MyApp::Configuration << "path/to/additional/yaml_file.yml"
MyApp::Configuration << { 'additional' => 'configuration' }
MyApp::Configuration.additional #=> 'configuration'
Note that if you pass a path to a YAML file, a key will be created to store the contents of the file, named after the file name. If the key already exists, the new values will be deep-merged into the existing values.
In the example above, the data in the yaml_file.yml
file can be accessed using
MyApp::Configuration.yaml_file
.
Other Notes
If you want to use Configoro outside of Rails or your gemset, you can require
the configoro/simple
file. This file defines a subset of the Configoro
object you can use to access your configuration. You will need to set
{Configoro.paths} manually, and the Configoro::Hash
object will have the same
functionality as a normal Hash, without all the bells and whistles described
above.
If you then "upgrade" your environment to a full-fledged Rails or gem-ified
environment (perhaps by running your app's environment.rb
file, be sure to
run {Configoro.reset_paths} before requiring the configoro
gem file.