Blog

Gavin Pickin

February 24, 2015

Spread the word


Share your thoughts

CommandBox is a whole system in itself, and when developing for CommandBox, like you would other applications, debugging is important. By default if you have any errors in your code, CommandBox outputs the error message, and a stack trace to the user in the console… and they will be returned to the prompt. This is great for you as a developer of said command, but its not very user friendly, so how can or should you handle errors in CommandBox.

As with any code, if you are concerned it might fail, you can try catch, and rethrow the error for a more useful error message, but CommandBox also has Controlled Errors. Controlled Errors is a function all Command have access to, that allows more user friendly ways to announce an error to a user. You can in fact, report multiple errors in a single command. In my kiwiSays command, I could throw an error for each of the settings required for kiwiSays addWebsite. I could throw an error for a badly formed URL, I could throw an error for a website Root path that does not exist, and if they try and use PHP as their CFML Engine I could nicely inform them that PHP is not a Cool Fab Markup Language Engine.

How do I use a CommandBox Error?

if( !directoryExists( ARGUMENTS.websitePath ) ) {
    error( "#ARGUMENTS.websitePath#: No such directory - Please enter a valid relative or full path" );
}

The error function takes a string argument, and outputs to the screen like this



Why use the built in Error function? 

Of course, you could output your own messages, using some great text helpers like this

print.redBoldLine(‘ERROR’);
print.redonYellowBoldLine(‘ERROR’);
print.greenLine(‘ERROR’);
print.blueonRedText(‘ERROR’);


While they might look cool, and you can customized the output… you lose consistency, but you also lose some other helper methods. In my example, I need to check several settings, before creating or updating conf files and restarting apache, so instead of managing how many errors I have had, I can just use the hasError()

if ( hasError() ) {
     return;
}

 

What does that return do?

If you are in the main Run method, and return, you are ending the command run cycle and output.
If you do not want to stack up errors, you can just return the error and skip using the hasError().

if ( url == “”) {
     return error( “Please enter a valid URL” );
}

Remember, if you use some clean code ideas from last weeks post, and you have your code refactored into sub functions… and you return an error, it only returns you to your main Run method, so it will not return/exit back to the command prompt, so you will need to do something like this.

validateRequiredSettings( ARGUMENTS.websiteURL, ARGUMENTS.websitePath, ARGUMENTS.engine );
if ( hasError() ) { 
    return; 
}

 

Of course, talking with Brad, we thought it would be a good addition for a future version for a Deep Exit… as it would eliminate some boiler plate code. We’ll add a JIRA ticket for that and hope to see that soon, the beauty of open source, maybe we could add that for them.

Remember, just because errors are errors, doesn’t make them bad, use them for good and give your users meaningful feedback, use Controlled Errors.
 

Add Your Comment

Recent Entries

CBWIRE 2.2 Released

CBWIRE 2.2 Released

We're excited to announce the release of CBWIRE 2.2. This release includes several added enhancements, such as new lifecycle hooks and simplified Turbo Drive integration. We changed the previous lifecycle hook of mount() to onMount() to be consistent, and several bugs were squashed.

Maria Jose Herrera
Maria Jose Herrera
January 09, 2023
FORGEBOX v7.1.0 Released

FORGEBOX v7.1.0 Released

We are so happy to announce a minor release for our package management system. In this release, we take care of some bug fixes reported and a lot of work for our elastic search engine. Now better search results with an improved response time. We have updated our core modules to the latest versions for better security and performance.

Javier Quintero
Javier Quintero
December 30, 2022
Favorite 2022 Ortus Content

Favorite 2022 Ortus Content

2022 was quite the year. For us, it was all about delivering exceptional content and service to our amazing community of developers. That's why we updated our tools, released new products, and announce upcoming projects and initiatives we are working on for 2023.

We know 2023 will be awesome but 2022 was amazing too. Read on and don't miss anything, review the top content we released in 2022 and improve your projects in 2023. Happy New Year!

Maria Jose Herrera
Maria Jose Herrera
December 29, 2022