Upgrading to ColdBox 8

The official ColdBox 8 upgrade guide

The major compatibility issues will be covered, as well as how to upgrade to this release from previous ColdBox versions smoothly. You can also check out the What's New guide to give you a full overview of the changes.

An upgrade from ColdBox 7 should not incur any breaking changes, but you should still read through the guide to ensure you are not using any deprecated features.

ColdFusion 2018 Support Dropped

ColdFusion 2018 support has been dropped. Adobe doesn't support them anymore, so neither do we.

Removals

CacheBox Tag Interfaces: ICacheProvider, IStats

The old interfaces that had been marked for deprecation in 6 are now removed. If you have custom cache providers or stats providers, you will need to update them to extend from the base classes:

  • coldbox.system.cache.ICacheProvider -> coldbox.system.cache.providers.ICacheProvider

  • coldbox.system.cache.IStats -> coldbox.system.cache.util.IStats

BeanPopulator

The BeanPopulator class has been removed. This class was deprecated in ColdBox 6 and was replaced by the ObjectPopulator class. Please use coldbox.system.core.dynamic.ObjectPopulator instead.

Client Flash

The Client Flash has been removed as it was deprecated in v6. The client scope is a very old, unperformant and insecure way of storing data. We recommend using CacheBox or Session scope instead.

ColdBox Util Env/System Methods

The following methods were removed in preference to the Environment Delegate class: coldbox.system.core.delegates.Env.

/**
* @deprecated Refactor to use the Env Delegate: coldbox.system.core.delegates.Env
*/
function getSystemSetting( required key, defaultValue ){
    return new coldbox.system.core.delegates.Env().getSystemSetting( argumentCollection = arguments );
}

/**
* @deprecated Refactor to use the Env Delegate: coldbox.system.core.delegates.Env
*/
function getSystemProperty( required key, defaultValue ){
    return new coldbox.system.core.delegates.Env().getSystemProperty( argumentCollection = arguments );
}

/**
* @deprecated Refactor to use the Env Delegate: coldbox.system.core.delegates.Env
*/
function getEnv( required key, defaultValue ){
    return new coldbox.system.core.delegates.Env().getEnv( argumentCollection = arguments );
}

Binder.getProperty() default Argument Removed

The default argument was deprecated in ColdBox 6 and has now been removed. Please use defaultValue instead.

Binder.getCacheBoxConfig() Removed

The getCacheBoxConfig() method was deprecated in ColdBox 6 and has now been removed. Please use getCacheBox() instead.

RequestContext SES Methods Removed

The following methods were removed from the RequestContext class. These methods were deprecated in ColdBox 7.

  • isSES()

  • setSESEnabled()

Router.getModulesRoutingTable() Removed

The getModulesRoutingTable() method was deprecated in ColdBox 7 and has now been removed. Please use getModuleRoutingTable() instead.

Router.includeRoutes() removed

The includeRoutes() method was deprecated in ColdBox 6 and has now been removed. This was for cfm routers which are no longer in use.

Router.with() and endWith() removed

The with() and endWith() methods were deprecated in ColdBox 7 and have now been removed. Please use the group() method with closures instead.

// Old way - removed
with( namespace = "luis" )
    .addRoute(
        pattern = "contactus",
        view    = "simpleview"
    )
    .addRoute(
        pattern      = "contactus2",
        view         = "simpleview",
        viewnoLayout = true
    )
    .endWith();

// New way - use group() with closure
group( { namespace : "luis" }, ( options ) => {
    route( pattern: "contactus" ).toView( view: "simpleview" );
    route( pattern: "contactus2" ).toView( view: "simpleview", noLayout: true );
} );

Router.addRoute() matchVariables Argument Removed

The matchVariables string argument that mimicked a query string was deprecated in ColdBox 6 and has now been removed. Please use the rc or prc struct arguments instead.

// Old way - removed
router.addRoute(
        pattern : "/myroute",
        handler : "myHandler",
        action : "myAction",
        matchVariables : "id=1&name=test"
    )

// New way - use rc or prc
router.addRoute(
        pattern : "/myroute",
        handler : "myHandler",
        action : "myAction",
        rc : { id = 1, name = "test" }
    )

Deprecations

The following methods were deprecated in ColdBox 7 and will be removed in ColdBox 9.

Super Type Methods

  • renderView() -> use view()

  • renderLayout() -> use layout()

  • renderExternalView() -> use externalView()

  • announceInterception() -> use announce()

  • populateModel() -> use populate()

ScheduledExecutor

  • newSchedule() -> use newTask()

AI-Assisted Upgrade Instructions

The following instructions are designed to help AI assistants inspect and automatically upgrade ColdBox applications from version 7 to version 8.

Code Inspection Patterns

When analyzing ColdBox applications for upgrade compatibility, check for these patterns:

1. Cache Provider Interface Usage

Look for implementations extending deprecated interfaces:

// Search for these deprecated patterns:
- extends="coldbox.system.cache.ICacheProvider"
- extends="coldbox.system.cache.IStats"

2. BeanPopulator Usage

// Search for BeanPopulator instantiation or injection:
- new coldbox.system.core.dynamic.BeanPopulator()
- property name="beanPopulator" inject="BeanPopulator"
- wirebox.getInstance( "BeanPopulator" )

3. Client Flash Scope Usage

// Search for client flash scope references:
- flash.setFlash()
- flash.getFlash()
- flashScope="client"
- setNextEvent( flashScope="client" )

4. Environment Method Usage

// Search for deprecated util methods:
- getSystemSetting()
- getSystemProperty()
- getEnv()
// When found in non-Env delegate contexts

5. Deprecated Binder Methods

// In WireBox binders, search for:
- .getProperty( default=
- .getCacheBoxConfig()

6. RequestContext SES Methods

// Search for these method calls:
- event.isSES()
- event.setSESEnabled()

7. Router Deprecated Methods

// Search for these router method calls:
- router.getModulesRoutingTable()
- router.includeRoutes()
- router.with()
- router.endWith()
- matchVariables argument in addRoute()

8. Super Type Method Usage

// Search for these method calls in handlers/interceptors:
- renderView()
- renderLayout()
- renderExternalView()
- announceInterception()
- populateModel()
- newSchedule() // in ScheduledExecutor context

Automated Replacement Rules

Apply these replacements when upgrading code:

Cache Provider Updates

// Replace:
extends="coldbox.system.cache.ICacheProvider"
// With:
extends="coldbox.system.cache.providers.ICacheProvider"

// Replace:
extends="coldbox.system.cache.IStats"
// With:
extends="coldbox.system.cache.util.IStats"

BeanPopulator to ObjectPopulator

// Replace all instances of:
BeanPopulator
// With:
ObjectPopulator

// Replace injection:
inject="BeanPopulator"
// With:
inject="ObjectPopulator"

Environment Method Delegation

// Replace utility method calls with Env delegate:
getSystemSetting( "key", "default" )
// With:
new coldbox.system.core.delegates.Env().getSystemSetting( "key", "default" )

// Or inject the delegate:
property name="env" inject="coldbox.system.core.delegates.Env";
// Then use:
env.getSystemSetting( "key", "default" )

Binder Method Updates

// Replace:
.getProperty( key, default=value )
// With:
.getProperty( key, defaultValue=value )

// Replace:
.getCacheBoxConfig()
// With:
.getCacheBox()

Router Method Updates

// Replace:
router.getModulesRoutingTable()
// With:
router.getModuleRoutingTable()

// Replace with() and endWith() patterns:
router.with( "api", function( route ) {
    route.get( "/users", "users.index" );
} ).endWith();
// With:
router.group( { prefix: "api" }, function( route ) {
    route.get( "/users", "users.index" );
} );

// Replace matchVariables:
router.addRoute(
    pattern="/route",
    handler="handler",
    matchVariables="id=1&name=test"
)
// With:
router.addRoute(
    pattern="/route",
    handler="handler",
    rc={ id=1, name="test" }
)

Super Type Method Updates

// Replace deprecated methods:
renderView() -> view()
renderLayout() -> layout()
renderExternalView() -> externalView()
announceInterception() -> announce()
populateModel() -> populate()
newSchedule() -> newTask()

Client Flash Removal

// Remove or replace client flash usage:
// Replace with session or cachebox alternatives
setNextEvent( url="page", flashScope="client" )
// With:
setNextEvent( url="page" ) // uses session by default
// Or:
setNextEvent( url="page", flashScope="session" )

Upgrade Validation

After applying automated changes, verify:

  1. Engine Compatibility: Ensure minimum ColdFusion 2021+ or Lucee 5.3+

  2. Test Coverage: Run existing test suites to validate functionality

  3. Cache Providers: Test custom cache provider implementations

  4. Module Compatibility: Verify all modules work with updated router methods

  5. Environment Variables: Ensure environment delegate usage works correctly

Manual Review Required

These patterns require manual developer review:

  • Custom cache providers extending old interfaces need logic review

  • Complex routing configurations using deprecated methods may need restructuring

  • Client flash scope usage requires architectural decisions for replacement

  • Environment method usage in performance-critical code may benefit from injection optimization

Completion Checklist

PreviousWhat's New With 8.0.0NextWhat is ColdBox

Last updated

Was this helpful?