onException

Announced any time an unhandled exception is thrown.

interceptData

• exception - Error struct

Interceptors are a powerful event-driven model inside CommandBox that allows you to listen to broadcasts from within the core code to respond to events and even influence execution. Interceptors are packaged within CommandBox Modules and can be for your own use, just debugging, or to share with the world.

To create a simple interceptor, re-create the simple folder structure below inside your CommandBox installation directory.

Creating An Interceptor

An interceptor is a CFC that has one or more methods whose names match the name of an interception point that is broadcast. Interceptors are packaged within CommandBox modules. When the module is loaded, the InterceptorService will register your interceptor and take care of calling it when necessary.

preModuleLoad

Announced before each module that is loaded.

interceptData

• moduleLocation - Path to the module

• moduleName - Name of the module

postModuleLoad

Announced after each module that is loaded.

interceptData

• moduleLocation - Path to the module

• moduleName - Name of the module

• moduleConfig

preModuleUnLoad

Announced before each module that is unloaded.

interceptData

• moduleName - Name of the module

postModuleUnload

Announced after each module that is unloaded.

interceptData

• moduleName - Name of the module

Here is a list of all the core interception points in CommandBox that you can listen to. Some have interceptData that comes along with them, while others don't. Remember, the interceptData struct is passed by reference. This means modifying any values directly in that struct will affect how processing continues afterwards inside of CommandBox where those values are used.

Click a category for more information.

preServerStart

Announced before a server starts. This fires after server.json has been located but before any configuration is resolved. Use this to override any user inputs, influence how the server's details are resolved, or to modify things like hostname before ports are bound.

interceptData

• serverDetails - A struct with the following keys used in starting the server

  • defaultName - The name of the server

  • defaultwebroot - The web root of the server
• serverProps - A struct with the parameters passed to the start command from the CLI. Omitted params will not be present.

  • See the help for the server start command to see the current list of parameters.

onServerStart

Announced as a server is starting after the configuration values have been resolved, but prior to the actual server starts. Use this to modify the settings for the server before it starts.

interceptData

• serverInfo - A struct with the following keys used in starting the server

  • name - The name of the server

onServerInstall

Announced when a server is starting and the cfengine is being installed. This gives you a chance to influence how the server is installed or to modify default settings before the server process actually starts. This is not announced for servers using a WARPath setting. It is announced every time a server is started, but you can use the installDetails.initialInstall flag to determine if this is the first time the engine is being installed for one-time tasks.

interceptData

• serverInfo - Same as onServerStart above

• installDetails A struct with the following keys:

onServerStop

Announced before a server stop.

interceptData

• serverInfo - Same as onServerStart above

preServerForget

Always fires before attempting to forget a server whether or not the forgetting is actually successful. Has access to all files and settings for the server.

interceptData

• serverInfo - Same as onServerStart above

postServerForget

Fires after a successful server forget. If the forget fails, this will not fire.

interceptData

• serverInfo - Same as onServerStart above

preInstall

Announced prior to installing a package. If a package has additional dependencies to install, each of them will fire this interception point.

interceptData

• installArgs - Struct containing the following keys used in installation of the package.

  • ID - The ID of the package to install

  • directory - Directory to install to. May be null, if none supplied.

  • save

onInstall

Announced while a package is being installed, after the package endpoint and installation directory has been resolved but before the actual installation occurs. This allows you to override things like the installation directory based on package type. Any values updated in the interceptData struct will override what the install command uses.

interceptData

• installArgs - Same as preInstall above

• installDirectory - Directory that the package will be installed in

postInstall

Announced after an installation is complete. If a package has additional dependencies to install, each of them will fire this interception point. This fires even if an install is skipped due to an existing package that satisfies the dependencies, or if the package is already installed.

interceptData

• installArgs - Same as preInstall above

preUninstall

Announced before the uninstallation of a package.

interceptData

• uninstallArgs - Struct containing the following keys used in removal of the package

  • ID - ID of the package to uninstall

postUninstall

Announced after the uninstallation of a package.

interceptData

• uninstallArgs - Same as preUninstall above

preVersion

Announced before the new version is set in the package.

interceptData

• versionArgs - A struct containing the following keys:

  • version - The new version about to be set

postVersion

Announced after the new version is set in the package but before the Git repo is tagged.

interceptData

• versionArgs - Same as preVersion above.

onRelease

Announced after a new version is set using the bump command and after the Git repo is tagged.

interceptData

• directory - The working directory of the package

• version - The new version about was set

prePublish

Announced prior to publishing a package to an endpoint

interceptData

• publishArgs - A struct containing the following keys:

  • endpointName - The name of the endpoint being published to

postPublish

Announced after publishing a package to an endpoint

interceptData

• publishArgs - Same as prePublish above.

• boxJSON - Same as prePublish above.

Announced prior to unpublishing a package from an endpoint

interceptData

• unpublishArgs - A struct containing the following keys:

  • endpointName - The name of the endpoint being published to

postUnpublish

Announced after unpublishing a package from an endpoint

interceptData

• unpublishArgs - Same as preUnpublish above.

• boxJSON - Same as preUnpublish above.

You have the ability to create your own interception points on top of the core ones in CommandBox. This can be handy to employ your own event listener model within a module-- which could be comprised of multiple models and commands. Interceptors that listen to custom interception points work the exact same as interceptors that listen to core interception points. In fact, the same interceptor file can listen to both.

Register

To register your custom interception point with InterceptorService, place the following config in your module's ModuleConfig.cfc. This module is registering a custom interception point called onCustomEvent.

Announce

It's up to you to decide when to announce this event and what intercept data you want to provide to it. To announce, use the announceInterception method in the InterceptorService. Here's a model that shows how:

preCommand

Announced before the execution of a command. This fires after all command parameters have been evaluated, including expressions. If piping the output of one command into another in a command chain, this will fire twice-- once for each command in the chain.

interceptData

• commandInfo - A struct containing the following keys about the command to execute

  • commandString - A string representing the command name

  • commandReference - The instantiated Command CFC

  • parameters

• parameterInfo - A struct containing the following keys about the processed parameters for the command execution

  • positionalParameters - An array of parameter values

  • namedParameters

preCommandParamProcess

preCommand fires after expression, system setting, and colon param expansions have already occurred. preCommandParamProcess will fire prior to that so you can affect the system prior to the time the system settings are expanded in parameter values.

• commandInfo - Same as above

• parameterInfo - Same as above

postCommand

Announced immediately after command execution is complete. If more than one command is piped together in a command chain, this is announced after each command in the chain.

interceptData

• commandInfo - Same as preCommand above

• parameterInfo - Same as preCommand above

prePrompt

Announced prior to drawing the prompt in the interactive shell. This interception point can be used to customize the text of the prompt by modifying the prompt variable in intercept data which is an ANSI-formatted string to be output before the cursor.

interceptData

• prompt - An ANSI-formatted string containing the prompt text. Replacing this value will override the prompt.

preProcessLine

Pre and post command fire before and after each command, but that means they fire twice for something like:

preProcessLine will fire only once for the above command after the user hits enter but before anything is processed.

interceptData

• line - A string representing the line typed into the shell. Changing the contents of this string will override what actually gets executed.

postProcessLine

Pre and post command fire before and after each command, but that means they fire twice for something like:

postProcessLine will fire only once for the above command after the entire line has been executed. Any output is already sent to the console by the time this interception point fires.

interceptData

• line - A string representing the line that was just executed in the shell.

onCLIStart

Announced when shell first starts, but before any commands are run or output has been flushed to the console.

interceptData

• shellType - The string interactive if starting the interactive shell, or command if running a one-off command and exiting

• args - An array of arguments provided from the OS when box was executed.

• banner - A string containing the CommandBox banner text that displays when in interactive mode.

This fires every time the reload command runs and a fresh shell is created.

onCLIExit

Announced right before the shell exits and control is returned back to the OS. This fires every time the reload command runs right before the shell is destroyed and re-created.