Today we've released a new version of CFConfig-- your friendly neighborhood CLI for configuring Adobe and Lucee servers.  CFConfig sees a lot of little releases that we don't announce, but they are usually very small little releases adding a single setting here or there.  Today's release has a nice collection of brand new features that seemed worth talking about.

Get the new version

To play with the latest version of CFConfig, just run

CommandBox> update --system

The latest docs are located here:

https://cfconfig.ortusbooks.com/

If you find any issues or bugs, please report them right away in Slack or our ticket system, JIRA.

New Features

Here's an overview of the new things we've added.

IncludeList and excludeList

This feature applies to the following commands:

• cfconfig import
• cfconfig export
• cfconfig transfer

You can customize what config settings are transferred with the includeList and excludeList params. If at least one include pattern is provided, ONLY matching settings will be included. Nested keys such as datasources.myDSN or mailservers[1] can be used. You may also use basic wildcards in your pattern. A single * will match any number of chars inside a key name. A double ** will match any number of nested keys.

# Include all settings starting with "event"
cfconfig transfer from=.CFConfig.json includeList=event*
# Exclude all keys called "password" regardless of what struct they are in
cfconfig transfer from=.CFConfig.json excludeList=**.password

Append flag

This feature applies to the following commands:

• cfconfig import
• cfconfig export
• cfconfig transfer
• cfconfig set

Use the append parameter to merge incoming data with any data already present. For example, if a server already has one datasource defined and you import a JSON file with 2 more unique datasources, the --append flag will not remove the pre-existing one.

cfconfig transfer from=.CFConfig.json includeList=datasources --append
cfconfig set datasources={"brad":{"class":"test","dbdriver":"name"}} --append

JSON Expansion Replacements

This feature applies to the following commands but ONLY where the "to" destination is a JSON file:

• cfconfig import
• cfconfig export
• cfconfig transfer

Note, the replace:foo=bar syntax below will work on the cfconfig transfer command, but due a dependency on a new feature in the bleeding edge of Commandbox, you'll need to be on the bleeding edge of CommandBox 5.4 to use it with cfconfig export and cfconfig import.

If you usually replace sensitive or volatile information in a JSON export with env var expansions like $ {DB_PASSWORD}, you can do this automatically my supplying one or more replace mappings. The key is a regular expression to match a key in the format of datasources.myDSN.password and the value is the name of the env var to use. The values will be written to a .env file in the current working directory. You can override this path with the dotenvFile param, or pass an empty string to disable it from being written.

cfconfig transfer to=.CFConfig.json replace:datasources\.myDSN\.password=DB_PASSWORD

Remember, the first part of your replace is a regular expression so make sure you use proper syntax!

As the value is a regular expression, you can use back references like \1 in your env var to make them dynamic. This example would create env vars such as DB_MYDSN_PASSWORD where MYDSN is your actual datasource name.

cfconfig tranfser to=.CFConfig.json replace:replace:datasources\.(.*)\.password=DB_\1_PASSWORD

Any valid regex is possible for some clever replacements. This example would create env vars such as DB_MYDSN_PORT, DB_MYDSN_HOST, and DB_MDSN_DATABASE

cfconfig tranfser to=.CFConfig.json replace:datasources\.(.*)\.(password|class|port|host|database)=DB_\1_\2 dotenvFile=../../settings.properties

To avoid having to pass these replacements every time you transfer your config, you can set then as a global setting for the commandbox-cfconfig module.

# Replace all mail server passwords with $ {MAIL_PASSWORD}
config set modules.commandbox-cfconfig.JSONExpansions[mailServers.*.password]=MAIL_PASSWORD

# Dynamically replace with $ {DB_MYDSN_password}, $ {DB_MYDSN_CLASS}, $ {DB_MYDSN_PORT}, etc
config set modules.commandbox-cfconfig.JSONExpansions[datasources\.(.*)\.(password|class|port|host|database)]=DB_\1_\2

# Use default env var name for all settings starting with "requestTimeout" and replace with $ {REQUEST_TIMEOUT} and $ {REQUEST_TIMEOUT_ENABLED}
config set modules.commandbox-cfconfig.JSONExpansions[requestTimeout.*]=

Note, the config set syntax shown above require at least CommandBox 5.4.0

Using "deep" property names

This feature applies to the following commands:

• cfconfig show
• cfconfig set

The cfconfig set and cfconfig show commands now work the same as package set/show in that you can use "deep" keys to access nested properties.

cfconfig show datasources.myDSN
cfconfig show mailServers[1].port
cfconfig set loggers.deploy.level=debug
cfconfig set datasources.myDSN.password=myPass

Keep in mind that examples such as the last line above can create invalid config if you don't already have a datasource called myDSN.  If you're needing to create new complex objects, or you're not sure if they will exist, use the other CFConfig namespaces like cfconfig datasource save which will ensure complete settings are saved.