Archive for the ‘Releases’ Category

CFWheels 2.2 Released

It’s been a while coming. Can I blame the pandemic? Lots of nice little tweaks and fixes in this version. Please see the changelog for all details.

Download zip

If updating from CFWheels 2.1.x:

It should be an easy upgrade , just swap out the wheels folder.

If updating from CFWheels 2.0.x:

  • replace your wheels folder from the one in the download, and
  • outside the wheels folder, ensure you’ve got a file at events/onabort.cfm and create it if needed.
  • rename any instances of findLast() to findLastOne() (this has been changed due to Lucee 5.3 having a new inbuilt function called findLast() which clashes with the wheels internals)

As always, a huge thanks to all contributors – stay safe out there!

CFWheels 2.1 Released

Today sees the release of CFWheels 2.1. Only a couple of bug fixes since the beta, so please refer to the changelog for a list of all changes.

Download now (zip)

If updating from CFWheels 2.0.x:

  • replace your wheels folder from the one in the download, and
  • outside the wheels folder, ensure you’ve got a file at events/onabort.cfm and create it if needed.
  • rename any instances of findLast() to findLastOne() (this has been changed due to Lucee 5.3 having a new inbuilt function called findLast() which clashes with the wheels internals)

Happy Easter, and stay safe!

CFWheels 2.1.0-beta Now Available

It’s been far too long in the making, but the beta for 2.1 has now arrived! Please do check it out: this should be considered an essential upgrade for anyone on 2.x. A huge thanks to all have contributed!

Make sure to check the “Potenitally Breaking Changes” section below, and please report any bugs.

What’s New:


Probably the most obvious change in 2.1 beta is the new internal user interface. Previously, Wheels internal pages like test outputs and routing tables could accidentally be broken by your app, as they extended your Controller.cfc by default. Now, they’re completely isolated, and have been significantly beefed up to show everything that you might want to look at as a developer. 

The new GUI has it’s own dedicated internal routes which can be accessed directly at /wheels/info (assuming you’ve got URL rewriting on) or via the usual links in the debug footer. 

It’s made up of six main sections:

  • General Wheels info – which displays all the settings for your development environment, such as datasources and other core configuration;   
  • a new routing table – which includes a handy route tester as well as a quick search;   
  • improved test outputs so you can more easily access unit tests for your app, core tests if you’re on the master branch, and plugin tests if they’re available;   
  • a new database migration interface, which allows for SQL previews, so you can actually check your migration is going to do what you think it’s going to do before executing;   
  • a more comprehensive documentation output, which includes your own autogenerated application docs as well as the internal wheels function references,   
  • and a better plugins list, showing all the information we know about any installed plugins. 

This GUI is only available in development mode by default, but can be enabled in other modes – this isn’t recommended, but it can be done if you really need to check the configuration or try and track something specific down. You can enable it via set(enablePublicComponent=true) in your environment specific configuration files. 

Improved CORS handling

Next up is some much needed and improved CORS handling. CORS, or Cross-Origin Resource Sharing, will be very familiar to any of you who have a javascript component or fully fledged progressive web app which runs on one domain, but needs to get information from another. A full explanation of CORS is probably beyond the scope of this post, but if you’re thinking of running your own API on a standalone domain where other applications talk to it, you’ll need to be able to handle CORS.

In Wheels 2.0, you could handle CORS requests, but they could only be configured in a very broad way. For instance, the CORS Allow Methods just returned all methods by default in an OPTIONS request, which kinda defeated the whole point.

The CORS Headers –  Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Credentials can now be directly set by their respective functions. 

However, for most people, a new helper configuration, accessControlAllowMethodsByRoute() will be the single most useful function to set: it allows for automatic matching of available methods for a route and sets the CORS Header Access-Control-Allow-Methods automatically; so now when your OPTIONS request hits your wheels app, it will actually respond with the available methods which are allowed for that resource endpoint. This makes it much easier to diagnose why certain requests might not get through, and means javascript libraries such as axios can respond more appropriately to hitting the wrong URL with the wrong HTTP method.

Improvements to mapper()

Redirects can now be put directly in the mapper() routing call, so you can quickly add a simple redirect for a route if you need.

mapFormat can now be set as false, which bypasses the additional ‘.[format]’ routes which were put in by default for each resource. So if you don’t use them, you can now just turn them off, and make your routing table a lot cleaner. This can be set either globally on the mapper() call itself, or on a per resource basis when using resources()

params._json if request is Array

Previously, if you POSTed or PUT/PATCHed json to an endpoint with an array as it’s root element, it would just get ignored, and you’d not be able to access it in the params struct. This has now been changed and if the incoming payload is a json array, it will be available at params._json which matches rails conventions.

New FlashAppend Behaviour

You can now change the default flash behaviour to append to an existing key, rather than directly replacing it. To turn on this behaviour, add set(flashAppend=true) to your /config/settings.cfm file. This allows you to more easily collect flash notifications during a request:

Plugin performance

The plugins system has been reverted back to 1.x behaviour, as it was simply non-performant; more on this in a future post.

Full Changelog:

Potentially breaking changes

  • The new CFWheels internal GUI is more isolated and runs in it’s own component: previously this was extending the developers main Controller.cfc which caused multiple issues. The migrator, test runner and routing GUIs have therefore all been re-written.
  • The plugins system behaviour no longer chains multiple functions of the same name as this was a major performance hit. It’s recommended that plugin authors check their plugins to run on 2.1
  • HTTP Verb/Method switching is now no longer allowed via GET requests and must be performed via POST (i.e via _method)

Model Enhancements

  • Migrator now automatically manages the timestamp columns on addRecord() and updateRecord() calls – #852 [Charley Contreras]
  • Migrator correctly honors CFWheels Timestamp configuration settings (setUpdatedAtOnCreate, softDeleteProperty, timeStampMode, timeStampOnCreateProperty, timeStampOnUpdateProperty) – #852 [Charley Contreras]
  • MSSQL now uses NVARCHAR(max) instead of TEXT #896 [Reuben Brown]
  • Allow createdAt and updatedAt to be explicitly assigned using the allowExplicitTimestamps=true argument – #887 – [Adam Chapman]

Controller Enhancements

  • New set(flashAppend=true) option allows for appending of a Flash key instead of replacing – #855 – [Tom King]
  • flashMessages() now checks for an array of strings or just a string and outputs appropriately – #855 – [Tom King]
  • flashInsert() can now accept a one dimensional array – #855 – [Tom King]

Bug Fixes

  • Allow uppercase table names containing reserved substrings like OR and AND – #765 [Dmitry Yakhnov, Adam Chapman]
  • Calculated properties can now override an existing property – #764 [Adam Chapman, Andy Bellenie]
  • Filters are now correctly called if there is more than one after filter – #853 [Brandon Shea, Tom King, Adam Chapman]
  • Minor fix for duplicate debug output in the test suite – #176 [Adam Chapman, Tom King]
  • Convert handle to a valid variable name so it doesn’t break when using dot notation – #846 [Per Djurner]
  • The validatesUniquenessOf() check now handles cases when duplicates already exist – #480 [Randall Meeker, Per Djurner]
  • validatesConfirmationOf() now has a caseSensitive argument to optionally perform a case sensitive comparison – #918 [Tom King]
  • sendFile() no longer expands an already expanded directory on ACF2016 – #873 [David Paul Belanger, Tom King, strubenstein]
  • Automatic database migrations onApplicationStart now correctly reference appropriate Application scope – #870 [Tom King]
  • usesLayout() now can be called more than once and properly respects the order called – #891 [David Paul Belanger]
  • Migrator MSSQL adapter now respects Time and Timestamp Column Types – #906 [Reuben Brown]
  • Automatic migrations fail on application start – #913 [Adam Chapman]
  • Default cacheFileChecking to true in development mode – [Adam Chapman, Steve Harvey]
  • Migrator columnNames list values are now trimmed – #919 [Adam Chapman]
  • Fixes bug when httpRequestData content is a JSON array – #926 [Adam Chapman]
  • When httpRequestData content is a JSON array, contents are now automatically added to params._json – #939 [Tom King]
  • Fixes bug where Migrator $execute() always appends semi-colon – #924 [Adam Chapman]
  • Fixes bug where model createdAt property is changed upon update – #927 [Brandon Shea, Adam Chapman]
  • Fixed silent application.wheels scope exception hampering autoMigrateDatabase – #957 [Adam Chapman, Tom King]


  • Added the ability to pass &lock=false in the URL for when reload requests won’t work due to locking – [Per Djurner]
  • Basic 302 redirects now available in mapper via redirect argument for GET/PUT/PATCH/POST/DELETE – #847 – [Tom King]
  • .[format] based routes can now be turned off in resources() and resource() via mapFormat=false – #899 – [Tom King]
  • mapFormat can now be set as a default in mapper() for all child resources() and resource() calls – #899 – [Tom King]
  • HEAD requests are now aliased to GET requests #860 – [Tom King]
  • Added the includeFilters argument to the processRequest function for skipping execution of filters during controller unit tests – [Adam Chapman]
  • Added the useIndex argument to finders for adding table index hints #864 – [Adam Chapman]
  • HTTP Verb/Method switching is now no longer allowed via GET requests and must be performed via POST #886 – [Tom King]
  • CORS Header Access-Control-Allow-Origin can now be set either via a simple value or list in accessControlAllowOrigin() #888 [Tom King]
  • CORS Header Access-Control-Allow-Methods can now be set via accessControlAllowMethods(value) #888 [Tom King]
  • CORS Header Access-Control-Allow-Credentials can now be turned on via accessControlAllowCredentials(true)#888 [Tom King]
  • accessControlAllowMethodsByRoute() now allows for automatic matching of available methods for a route and sets CORS Header Access-Control-Allow-Methods appropriately #888 [Tom King]
  • CORS Header can now be set via accessControlAllowHeaders(value) #888 [Tom King]
  • Performance Improvement: Scanning of Models and Controllers #917 [Adam Chapman]
  • Added the authenticityToken() function for returning the raw CSRF authenticity token #925 [Adam Chapman]
  • Adds enablePublicComponentenableMigratorComponent,enablePluginsComponent environment settings to completely disable those features #926 [Tom King]
  • New CFWheels Internal GUI #931 [Tom King]
  • pluginRunner() now removed in favour of 1.x plugin behaviour for performance purposes #916 [Core Team]
  • Adds validateTestPackageMetaData environment setting for skipping test package validation on large test suites #950 [Adam Chapman]
  • Added aliases for migrator.TableDefinition functions to allow singular variant of the columnNames property #922 [Sébastien FOCK CHOW THO]
  • onAbort is now supported via events/onabort.cfm #962 [Brian Ramsey]

CFWheels 2.0.2 Security Release

Today sees a security release for the 2.x series.

It is strongly recommended to update to CFWheels 2.0.2 if you are running either 2.0.0 or 2.0.1. This issue does not affect 1.x releases. This release introduces a potentially breaking change, so you are encouraged to test your application appropriately before deploying. Thanks to Bryan Welter for bringing it to our attention.

Download 2.0.2

Potential Breaking Changes

  • Blank strings in SQL are no longer converted to null

CFWheels 2.0.1 maintenance Release

Today sees a maintenance release for the 2.x series.

Download 2.0.1 today to fix the following:

Bug Fixes

  • Fixes reload links on application test suite page – #820 [Michael Diederich]
  • Set dbname in cfdbinfo calls when using custom database connection string – #822 [Per Djurner]
  • Fixes humanize() function – #663 [Chris Peters, Per Djurner, kmd1970]
  • Enables the rel attribute for stylesheetlinkTag() – #834 [Michael Diederich]
  • Returning a NULL value from a query with NULL support enabled no longer throws an error – #834 [Michael Diederich]
  • Accessing a route with incorrect verb now provides a more useful error message – #800 [Tom King]
  • Fixed bug with arrays in URLs – #836 [Michael Diederich, Per Djurner]
  • startFormTag now properly applies the method attribute – #837 [David Paul Belanger]
  • Incompatible plugin notice now ignores patch releases unless specified – #840 [Risto, Tom King]

CFWheels 1.4.6 maintenance Release

Today sees a maintenance release for the 1.4.x series. Please note that as 2.0 is now released, future updates to the 1.x branch will be limited to essential bug fixes only.

Download 1.4.6 today to fix the following:

Bug Fixes

  • Made humanize() keep spaces in input.
  • Added spatial datatypes for MySQL.
  • Scope variable to avoid object being returned as NULL.
  • Include “MariaDB” in database check connection string.
  • Fixes MySQL attempts to insert nulls for blank strings.

CFWheels 2.0 Released

Ok, it’s been a while, but *finally*, CFWheels 2.0 has gone gold!

  • Direct Download: Download zip
  • Commandbox quick install : install cfwheels (Just downloads and unzips)
  • Commandbox install wizard via CFWheels CLI (with url rewriting included):  wheels new
    (make sure your version of the CLI is up to date with install cfwheels-cli)

Make sure to check the “Breaking Changes” section, and please report any bugs.

Needless to say, this has been a massive undertaking with over 1000 commits, and over a year in the making. The core team wishes to thank all the many contributors, testers, and well, just users of the framework. We think we’re in a pretty strong place to move forward with loads more exciting things in the future.

For a comprehensive list of changes, check the Changelog, but for a quick summary:

Need help upgrading? Check the upgrade notes, and feel free to post questions to the Google Group, or hit us up on the #cfwheels room on the CFML Slack Channel

CFWheels 2.0.0-beta.1 Now Available

It’s been about a year in the making, and well over 1000 commits, but the beta for 2.0 has now arrived! We’re still catching up on the main documentation as there’s so much to cover in this release, so bear with us a bit! In the meantime, please do check it out:

  • Direct Download: Download zip
  • Commandbox quick install : install [email protected] (Just downloads and unzips)
  • Commandbox install wizard via CFWheels CLI (with url rewriting included):  wheels new
    (make sure your version of the CLI is up to date with install cfwheels-cli)

Make sure to check the “Breaking Changes” section below, and please report any bugs.

Need a little help upgrading?

There will be some more posts coming up covering some of the big topics like routing & migrations, but in the meantime:

  • Check out Adam’s upgrade advisor plugin (Commandbox: install upgradeadvisor)
  • Get in touch via the Mailing List, Slack channel etc.


Model Enhancements

  • Support for passing in select=false to property() to not include a calculated property by default in SELECT clauses – #122 [Adam Chapman, Per Djurner]
  • Support for setting calculated properties to a specific data type – [Per Djurner]
  • Support for returnIncludedAs and returnIncluded arguments to properties() for returning nested properties – [Adam Chapman]
  • Support for calling updateProperty() with dynamic argument, e.g. updateProperty(firstName="Per") – [Per Djurner]
  • Support for using boolean transaction argument, e.g. update(transaction=false)#654 [Adam Chapman]
  • Support for MariaDB – #563 [AlexeiCF, Adam Chapman]
  • Model instance isPersisted() and propertyIsBlank() methods – #559 [Chris Peters]
  • Database Migrations (dbmigrate) now available in the core – #664 [Adam Chapman, Tom King, Mike Grogan]
  • Databases can now be automatically migrated to the latest version on application start – #766 [Tom King]
  • New timeStampMode setting ("utc", "local" or "epoch") for the createdAt and updatedAtcolumns – [Andy Bellenie]
  • Allow nested transactions – #732 [Andy Bellenie]
  • The handle argument to finders now set the variable name for the query so it’s easier to find in the debug output – [Per Djurner]
  • Support added for HAVING when using aggregate functions in the where argument – #483 [Per Djurner]
  • Added support for the JSON data type in the MySQL adapter – #759 [Joel Stobart]
  • Corrected mapping for text types in the MySQL adapter – #759 [Joel Stobart]
  • Added global setting, lowerCaseTableNames, to always lower case table names in SQL statements – [Per Djurner]

View Enhancements

  • flashMessages() are now in default layout.cfm – #650 [Tom King]
  • Added ability to override value in textField(), passwordField() and hiddenField()#633 [Per Djurner, Chris Peters]
  • Support for the method argument in buttonTo() helper – #761 [Adam Chapman]

Controller Enhancements

  • Support for HTTP verbs, scopes, namespaces, and resources in routes (ColdRoute) [Don Humphreys, James Gibson, Tom King]
  • Support for passing in ram:// resources to sendFile()#566 [Tom King]
  • Extended sendMail() so that it can return the text and/or html content of the email – #122 [Adam Chapman]
  • renderWith() can now set http status codes in header with the status argument – #549 [Tom King]
  • Cross-Site Request Forgery (CSRF) protection – #613 [Chris Peters]
  • Parse JSON body and add to params struct – [Tom King, Per Djurner]

Bug Fixes

  • Fixes skipped model instantiation due to Linux file case sensitivity – #643 [Adam Chapman, Tom King]
  • Added spatial datatypes for MySQL – #660 [Normal Cesar]
  • Made humanize() keep spaces in input – #663 [Per Djurner, Chris Peters]
  • Avoid double redirect error when doing delayed redirects from a verification handler function – [Per Djurner]
  • Fixes attempts to insert nulls for blank strings – #654 [Andy Bellenie, Per Djurner]
  • Fix for using validatePresenceOf() with default on update – [Andy Bellenie]
  • Fixes so paginated finder calls with no records include column names – #722 [Per Djurner]
  • Fixes “invalid data” error when using unsigned integers in MySQL – #768 [Per Djurner]


  • Plugins now distributed via [Tom King]
  • Update to the plugin system to allow overriding of the same framework method multiple times – #681 [James Gibson, Tom King]
  • Added ability to turn off incompatible plugin warnings from showing – [Danny Beard]
  • Plugins now have any java lib/class files automatically mapped onApplicationStart 731 [Andy Bellenie, Tom King]
  • Plugins now read version number off their box.json files and are displayed in debug area #68 [Tom King]
  • Plugin meta data as set in box.json now available in application.wheels.pluginMeta scope #68 [Tom King]


  • Redirect away after a reload request – [Chris Peters]
  • Support checking IP in http_x_forwarded_for when doing maintenance mode exclusions – [Per Djurner]
  • Support checking user agent string when doing maintenance mode exclusions – [Per Djurner]
  • Added JUnit and JSON format test results – [Adam Chapman]
  • Added empty application test directories – [Chris Peters, Adam Chapman]
  • Added default urlrewrite.xml to support Tuckey URL rewriting with Commandbox #649 – [Tom King]
  • Added beforeAll(), afterAll(), packageSetup(), packageTeardown() methods to test framework #651 – [Adam Chapman]
  • Added errorEmailFromAddress and errorEmailToAddress config settings – #95 [Andy Bellenie, Tony Petruzzi, Per Djurner]
  • Support for passing in any “truthy” value to assert() in tests – [Per Djurner]
  • Added /app/ mapping pointing to the root of the application – [Per Djurner]
  • Added a processRequest() function that simplifies testing controllers – [Per Djurner]
  • Added new embedded documentation viewer/generator for JavaDoc – #734 [Tom King]
  • Removes all references to Railo – #656 (Adam Chapman)
  • Made uncountable and irregular words configurable – #739 [Per Djurner]
  • Removed design mode – [Per Djurner]
  • Removed cacheRoutes setting – [Per Djurner]
  • The cacheFileChecking and cacheImages settings are now turned off in development mode – [Per Djurner]
  • Added includeErrorInEmailSubject setting – [Per Djurner]
  • Environment switching via URL can now be turned off via allowEnvironmentSwitchViaUrl#766 [Tom King]

Breaking Changes

  • Minimum Lucee version is now
  • Minimum ACF version is now 10.0.23 / 11.0.12.
  • Support for Railo has been dropped.
  • Rewrite and config files for IIS and Apache have been removed and has to be added manually instead.
  • The events/functions.cfm file has been moved to global/functions.cfm.
  • The models/Model.cfc file should extend wheels.Model instead of Wheels (models/Wheels.cfc can be deleted).
  • The controllers/Controller.cfc file should extend wheels.Controller instead of Wheels(controllers/Wheels.cfc can be deleted).
  • The init function of controllers and models should now be named config instead.
  • The global setting modelRequireInit has been renamed to modelRequireConfig.
  • The global setting cacheControllerInitialization has been renamed to cacheControllerConfig.
  • The global setting cacheModelInitialization has been renamed to cacheModelConfig.
  • The global setting clearServerCache has been renamed to clearTemplateCache.
  • The updateProperties() method has been removed, use update() instead.
  • Form labels automatically generated based on foreign key properties will drop the “Id” from the end (e.g., the label for the “userId” property will be “User”, not “User Id”).
  • Routes need to be updated to use the new routing system by calling mapper().
  • JavaScript arguments like confirm and disable have been removed from the link and form helper functions (use the JS Confirm and JS Disable plugins to reinstate the old behaviour).
  • Timestamping (createdAt, updatedAt) is now in UTC by default (set the global timeStampModesetting to local to reinstate the old behaviour).
  • Blank strings in SQL are now converted to null checks (e.g. where="x=''" becomes where="x IS NULL").
  • Tags are now closed in HTML5 style (e.g. <img src="x"> instead of <img src="x" />).
  • The encode argument to mailTo now encodes tag content and attributes instead of outputting JavaScript.
  • Class output is now dasherized (e.g. field-with-errors instead of fieldWithErrors).
  • The renderPage function has been renamed to renderView.

CFWheels 1.4.5 maintenance Release

Today sees another maintenance release for the 1.4.x series

Download 1.4.5 today to fix the following:

Bug Fixes

  • Display URL correctly in error email when on HTTPS – [Per Djurner]
  • Added the datetimeoffset data type to the Microsoft SQL Server adapter – [Danny Beard]
  • Fix for test link display in debug footer – #588 [Tom King]
  • Don’t include query string when looking for image on file through imageTag() – [Per Djurner]
  • Format numbers in paginationLinks() – [Per Djurner]
  • Correct plugin filename case on application startup – #586 [Chris Peters]
  • Clear out cached queries on reload – #585 [Andy Bellenie]

Also don’t forget to check the upgrade notes.

CFWheels 1.4.4 maintenance Release

Today sees another maintenance release for the 1.4.x series

Download 1.4.4 today to fix the following:

Bug Fixes

  • Check global “cacheActions” setting – #572 [Andy Bellenie, Per Djurner]
  • Fixed parsing for SQL IN parameters – #564 [Lee Bartelme, Per Djurner]
  • Pass through all arguments properly when using findOrCreateBy – #561 [Per Djurner]
  • Make it possible to disable session management on a per request basis – #493 [Andy Bellenie, Per Djurner]
  • Allow mailParams to be passed through to sendEmail() – #565 [Tom King]
  • Fixed inconsistency in form helpers for nested properties – [Marc Funaro, Per Djurner, Chris Peters]
  • Fixed issue with grouping on associated models – [Song Lin, Per Djurner]
  • Made the pagination() function available globally – #560 [Chris Peters, Per Djurner]

Also don’t forget to check the upgrade notes.