Confex

Deps Status Hex.pm Downloads Latest Version License Build Status Coverage Status

This is helper module that provides a nice way to read environment configuration at runtime. It’s inspired by Phoenix {:system, value} definition for HTTP port.

Installation

It’s available on hex.pm and can be installed as project dependency:

  1. Add confex to your list of dependencies in mix.exs:

        def deps do
          [{:confex, "~> 1.4.0"}]
        end
        ```
  2. Ensure confex is started before your application:

        def application do
          [applications: [:confex]]
        end
        ```

Usage

  1. Defining configurations

    Define your configuration in config.ex of your application.

        config :ap_cfpredictor, AssetProcessor.AMQP.Producer,
          queue: [
            name:        {:system, "OUT_QUEUE_NAME", "MyQueueOut"},
            error_name:  {:system, "OUT_ERROR_QUEUE_NAME", "MyQueueOut.Errors"},
            routing_key: {:system, "OUT_ROUTING_KEY", ""},
            durable:     {:system, "OUT_DURABLE", false},
            port:        {:system, :integer, "OUT_PORT", 1234},
          ],
        ```
    
      List of supported formats:
    
    * `var` - any bare values will be left as-is.
    * `{:system, "ENV_NAME", default}` - read string from system ENV, return `default` if it's nil.
    * `{:system, "ENV_NAME"}` - read string from system ENV, returns `nil` if environment variables doesn't exist.
    * `{:system, :string, "ENV_NAME", default}` - same as `{:system, "ENV_NAME", default}`.
    * `{:system, :string, "ENV_NAME"}` - same as `{:system, "ENV_NAME"}`.
    * `{:system, :integer, "ENV_NAME", default}` - same as `{:system, "ENV_NAME", default}`, but will convert value to integer if it's not `nil`. Default value type **will not** be changed.
    * `{:system, :integer, "ENV_NAME"}` - same as `{:system, :integer, "ENV_NAME", nil}`.
    * `{:system, :boolean, "ENV_NAME", default}` - same as `{:system, "ENV_NAME", default}`, but will convert value to boolean if it's not `nil`. Default value type **will not** be changed.
    * `{:system, :boolean, "ENV_NAME"}` - same as `{:system, :boolean, "ENV_NAME", nil}`.
  2. Reading configuration

    Read string values:

        iex> confex.get(:myapp, MyKey)
        "abc"
        ```
    
      Read integer values:
    
    confex.get(:myapp, MyIntKey)
    123
    ```

    Read map values:

        confex.get(:myapp, MyIntKey)
        [a: 123, b: "abc"]
        ```
  3. Using macros

    Confex is supplied with helper macros that allow to attach configuration to specific modules of your application.

        defmodule Connection do
          use Confex, otp_app: :myapp
        end
        ```
    
      `Connection` in this case will read configuration from app `:myapp` with key `Connection`. Also it will provide helper function `config/0` that will return values at run-time.
  4. Configuration validation

    Sometimes you want to validate configuration, for this you can define def validate_config(config) method, that will be called on each config/0 usage.

    Confex doesn’t give opinions on a validator to be used in overrided methods.

Configuration priorities

By using Confex macro in your module, you allow to provide compile-time defaults for it.

  1. Declare module

        defmodule MyModule do
          use Confex
        end
        ```
  2. Provide defaults when using it

        use MyModule,
          otp_all: :myapp,
          host: {:system, "HOST"}
        ```
    
      This configs will overwritten by any configuration that you have in your application env.

Helpful links