The configuration CFC has embedded environment control and detection built-in. Environments kan be detected by:

• regex matching against cgi.http_host

• detection of an environmental variable called ENVIRONMENT ( Coldbox 5.2 and higher )

• usage of a detectEnvironment() function

The first option (regex matching) is the easiest to use, but not very reliable if you are using multiple hostnames or commandbox for re-initialization.

Default: Regex matching against cgi.http_host

To detect your environments you will setup a structure called environments in your coldbox configuration with the named environments and their associated regular expressions for its cgi host names to match for you automatically. If the framework matches the regex with the associated cgi.http_host, it will set a setting called Environment in your configuration settings and look for that environment setting name in your CFC as a method by convention. That's right, it will check if your CFC has a method with the same name as the environment and if it exists, it will call it for you. Here is where you basically override, remove, or add any settings according to your environment.

Warning : The environment detection occurs AFTER the configure() method is called. Therefore, whatever settings or configurations you have on the configure() method will be stored first, treat those as Production settings.

environments = {
    // The key is the name of the environment
    // The value is a list of regex to match against cgi.http_host
    development = "^cf2016.,^lucee.,localhost",
    staging = "^stg"
};

The regex match will also create a global setting called "environment" which you can access and use like this:

if ( getSetting('environment') == 'development' ){
    doSomeMajik();
}

In the above example, I declare a development key with a value list of regular expressions. If I am in a host that starts with cf2016, this will match and set the environment setting equal to development. It will then look for a development method in this CFC and execute it.

/**
* Executed whenever the development environment is detected
*/
function development(){
    // Override coldbox directives
    coldbox.handlerCaching = false;
    coldbox.eventCaching = false;
    coldbox.debugPassword = "";
    coldbox.reinitPassword = "";

    // Add dev only interceptors
    arrayAppend( interceptors, {class="#appMapping#.interceptors.CustomLogger} );
}

Detection of an environmental variable called ENVIRONMENT

If you are using environmental variables for your different environments, you can specify an environmental variable called ENVIRONMENT and name it staging, development, testing etcetera, depending on the required environment. As in the regex example, a function named after your environment (e.g. staging() or development() ) will be called after your configure method.

Custom Environment Detection

If you are NOT using environmental variables you can use your own detection algorithm instead of looking at the cgi.http_host variable. You will NOT fill out an environments structure but actually create a method with the following signature:

string public function detectEnvironment(){
}

This method will be executed for you at startup and it must return the name of the environment the application is on. You can check for any condition which distinguishes your environment from your other environments. Als long as you return a environment name based on your own logic it will then store it and execute the method if it exists.

The basic configuration object has 1 method for application configuration called configure() where you will place all your configuration directives and settings:

Directives

Inside of this configuration method you will place several core and third-party configuration structures that can alter your application settings and behavior. Below are the core directives you can define:

This directive is how you will configure the for operation. Below are the configuration keys and their defaults:

This element defines custom conventions for your application. By default, the framework has a default set of conventions that you need to adhere too. However, if you would like to implement your own conventions for a specific application, you can use this setting, otherwise do not declare it:

This structure configures the interceptor service in your application.

throwOnInvalidStates

This tells the interceptor service to throw an exception if the state announced for interception is not valid or does not exist. Defaults to false.

customInterceptionPoints

This key is a comma delimited list or an array of custom interception points you will be registering for custom announcements in your application. This is the way to provide an observer-observable pattern to your applications.

Info Please see the section for more information.

This is an array of interceptor definitions that you will use to register in your application. The key about this array is that ORDER matters. The interceptors will fire in the order that you register them whenever their interception points are announced, so please watch out for this caveat. Each array element is a structure that describes what interceptor to register.

Warning : Important: Order of declaration matters! Also, when declaring multiple instances of the same CFC (interceptor), make sure you use the name attribute in order to distinguish them. If not, only one will be registered (the last one declared).

This structure is used to house module configurations. Please refer to each module's documentation on how to create the configuration structures. Usually the keys will match the name of the module to be configured.

component {

     function configure() {

         moduleSettings = {
             myModule = {
                someSetting = "overridden"
             }
        };
    }
}

This structure allows you to define a system-wide default layout and view.

//Layout Settings
layoutSettings = {
    // The default layout to use if NOT defined in a request
    defaultLayout = "Main.cfm",
    // The default view to use to render if NOT defined in a request
    defaultView   = "youForgot.cfm"
};

Hint Please remember that the default layout is Main.cfm

The CacheBox structure is based on the CacheBox declaration DSL, and it allows you to customize the caches in your application. Below are the main keys you can fill out, but we recommend you review the CacheBox documentation for further detail.

//cachebox configuration
cachebox = {
    // Location of the configuration CFC for CacheBox
    configFile = "config/CacheBox.cfc",
    // Scope registration for CacheBox
    scopeRegistration = {enabled=true,scope=application,key=cacheBox},
    // Default Cache Configuration
    defaultCache  = "views",
    // Caches Configuration
    caches      = {}
};

Info : We would recommend you create a config/CacheBox.cfc and put all your caching configuration there instead of in the main ColdBox configuration file. This will give you further portability and decoupling.

ConfigFile

An absolute or relative path to the CacheBox configuration CFC or XML file to use instead of declaring the rest of the keys in this structure. So if you do not define a cacheBox structure, the framework will look for the default value: config/CacheBox.cfc and it will load it if found. If not found, it will use the default CacheBox configuration found in /coldbox/system/web/config/CacheBox.cfc

ScopeRegistration

A structure that enables scope registration of the CacheBox factory in either server, cluster, application or session scope.

DefaultCache

The configuration of the default cache which will have an implicit name of default which is a reserved cache name. It also has a default provider of CacheBox which cannot be changed.

Caches

A structure where you can create more named caches for usage in your CacheBox factory.

The modules structure is used to configure the behavior of the ColdBox Modules.

modules = {
    // Will auto reload the modules in each request. Great for development but can cause some loading/re-loading issues
    autoReload = true,
    // An array of modules to load ONLY
    include = [],
    // An array of modules to EXCLUDE for operation
    exclude = [ "paidModule1", "paidModule2" ]
};

Danger Please be very careful when using the autoReload flag as module routing can be impaired and thread consistency will also suffer. This is PURELY a development flag that you can use at your own risk.

The logBox structure is based on the LogBox declaration DSL, see the LogBox Documentation for much more information.

//LogBox DSL
logBox = {
    // The configuration file without fileextension to use for operation, instead of using this structure
    configFile = "config/LogBox", 
    // Appenders
    appenders = {
        appenderName = {
            class="class.to.appender", 
            layout="class.to.layout",
            levelMin=0,
            levelMax=4,
            properties={
                name  = value,
                prop2 = value 2
            }
    },
    // Root Logger
    root = {levelMin="FATAL", levelMax="DEBUG", appenders="*"},
    // Granualr Categories
    categories = {
        "coldbox.system" = { levelMin="FATAL", levelMax="INFO", appenders="*"},
        "model.security" = { levelMax="DEBUG", appenders="console"}
    }
    // Implicit categories
    debug  = ["coldbox.system.interceptors"],
    info   = ["model.class", "model2.class2"],
    warn   = ["model.class", "model2.class2"],
    error  = ["model.class", "model2.class2"],
    fatal  = ["model.class", "model2.class2"],
    off    = ["model.class", "model2.class2"]
};

Info : If you do not define a logBox DSL structure, the framework will look for the default configuration file config/LogBox.cfc. If it does not find it, then it will use the framework's default logging settings.

ConfigFile

You can use a configuration CFC instead of inline configuration by using this setting. The default value is config/LogBox.cfc, so by convention you can just use that location. If no values are defined or no config file exists, the default configuration file is coldbox/system/web/config/LogBox.cfc.

These are custom application settings that you can leverage in your application.

You can read our section to discover how to use all the settings in your application.

The ColdBox directive is where you configure the framework for operation.

Application Setup

Info : Please note that there are no mandatory settings as of ColdBox 4.2.0. If fact, you can remove the config file completely and your app will run. It will be impossible to reinit the app however without a reinit password set.

Development Settings

reinitPassword

Protect the reinitialization of the framework URL actions. For security, if this setting is omitted, we will create a random password. Setting it to an empty string will allow you to reinitialize without a password. Always have a password set for public-facing sites.

handlersIndexAutoReload

Will scan the conventions directory for new handler CFCs on each request if activated. Use false for production, this is only a development true setting.

Implicit Event Settings

These settings map 1-1 from ColdBox events to the Application.cfc life-cycle methods. The only one that is not is the defaultEvent, which selects what event the framework will execute when no incoming event is detected via URL/FORM or REMOTE executions.

Extension Points

The ColdBox extension points are a great way to create federated applications that can reuse a centralized core instead of the local conventions. It is also a great way to extend some core classes with your own.

applicationHelper

A list or array of absolute or relative paths to a UDF helper file. The framework will load all the methods found in this helper file globally. Meaning it will be injected in ALL handlers, layouts and views.

viewsHelper

A list or array of absolute or relative paths to a UDF helper file. The framework will load all the methods found in this helper in layouts and views only.

modulesExternalLocation

A list or array of locations of where ColdBox should look for modules to load into your application. The path can be a cf mapping or cfinclude compatible location. Modules are searched and loaded in the order of the declared locations. The first location ColdBox will search for modules is the conventions folder modules

viewsExternalLocation

The CF include path of where to look for secondary views for your application. Secondary views look just like normal views except the framework looks in the conventions folder first and if not found then searches this location.

layoutsExternalLocation

The CF include path of where to look for secondary layouts for your application. Secondary layouts look just like normal layouts except the framework looks in the conventions folder first and if not found then searches this location.

handlersExternalLocation

The CF dot notation path of where to look for secondary events for your application. Secondary events look just like normal events except the framework looks in the conventions folder first and if not found then searches this location.

requestContextDecorator

The CF dot notation path of the CFC that will decorate the system Request Context object.

controllerDecorator

The CF dot notation path of the CFC that will decorate the system Controller

Exception Handling

exceptionHandler

The event handler to call whenever ANY non-catched exception occurs anywhere in the request lifecycle execution. Before this event is fired, the framework will log the error and place the exception in the prc as prc.exception.

invalidHTTPMethodHandler

The event handler to call whenever a route or event is accessed with an invalid HTTP method.

invalidEventHandler

This is the event handler that will fire masking a non-existent event that gets requested. This is a great place to place 302 or 404 redirects whenever non-existent events are being requested.

customErrorTemplate

The relative path from the application's root level of where the custom error template exists. This template receives a key in the private request collection called exception that contains the exception. By default ColdBox does not show robust exceptions, you can turn on robust exceptions by choosing the following template:

Application Aspects

handlerCaching

This is useful to be set to false in development and true in production. This tells the framework to cache your event handler objects as singletons.

eventCaching

This directive tells ColdBox that when events are executed they will be inspected for caching metadata. This does not mean that ALL events WILL be cached if this setting is turned on. It just activates the inspection mechanisms for whenever you annotate events for caching or using the runEvent() caching methods.

viewCaching

This directive tells ColdBox that when views are rendered, the cache=true parameter will be obeyed. Turning on this setting will not cause any views to be cached unless you are also passing in the caching parameters to your renderView() or event.setView() calls.

proxyReturnCollection

This is a boolean setting used when calling the ColdBox proxy's process() method from a Flex or SOAP/REST call. If this setting is set to true, the proxy will return back to the remote call the entire request collection structure ALWAYS! If set to false, it will return, whatever the event handler returned back. Our best practice is to always have this false and return appropriate data back.

implicitViews

Allows you to use implicit views in your application and view dispatching. You can get a performance boost if you disable this setting.

caseSensitiveImplicitViews

By default implicit views are case sensitive since ColdBox version 5.2.0, before this version the default was false.

autoMapModels

ColdBox by convention can talk to, use and inject models from the models folder by just using their name. However, once you built complex hierarchies you would have to specify the specific hierarchy or folder structure for the model; This is a limitation of conventions. Your choices before v5.2.0 was to map the objects yourself in the WireBox binder. Now, if you turn this setting to true, we will issue a mapDirectory() on the models directory for you.

This configuration structure is used to configure the dependency injection framework embedded in ColdBox.

binder

The location of the WireBox configuration binder to use for the application. If empty, we will use the binder in the config folder called by conventions: WireBox.cfc

singletonReload

A great flag for development. If enabled, WireBox will flush its singleton objects on every request so you can develop without any headaches of reloading.

Warning : This operation can cause some thread issues and it is only meant for development. Use at your own risk.

The layouts array element is used to define implicit associations between layouts and views/folders, this does not mean that you need to register ALL your layouts. This is a convenience for pairing them, we are in a conventions framework remember.

Before any renderings occur or lookups, the framework will check this array of associations to try and match in what layout a view should be rendered in. It is also used to create aliases for layouts so you can use aliases in your code instead of the real file name and locations.