ColdBox is a conventions-based HMVC web development framework for the BoxLang JVM Language and ColdFusion (CFML).
ColdBox Hierarchical MVC is the de-facto enterprise-level HMVC framework for the BoxLang JVM language and the ColdFusion (CFML) language. It's professionally backed, conventions-based, modular, highly extensible, and productive. Getting started with ColdBox is quick and painless. ColdBox takes the pain out of development by giving you a standardized methodology for modern web development with features such as:
Much More
It provides a set of reusable code and tools that can be used to increase your development productivity, as well as a development standard for working in team environments.
BoxLang is a modern dynamic JVM language developed by the ColdBox team that can be deployed on multiple runtimes: operating system (Windows/Mac/*nix/Embedded), web server, lambda, iOS, android, web assembly, and more. BoxLang combines many features from different programming languages, including Java, CFML, Python, Ruby, Go, and PHP, to provide developers with a modern, functional and expressive syntax.
ColdBox has been designed to work in both BoxLang and CFML language engines. However, it is extremely optimized for BoxLang, since it is the same team that develops the language and the framework.
Read more about BoxLang here:
The ColdBox Platform is open source and licensed under the License.
Copyright by Ortus Solutions, Corp
ColdBox, CacheBox, WireBox, and LogBox are registered trademarks of Ortus Solutions, Corp.
The Ortus Community is how to get help for our entire platform and modules: .
You can also join our Slack Box Team at:
We all make mistakes from time to time :) So why not let us know about it and help us out? We also love 😍 pull requests, so please star us and fork us at:
ColdBox is a professional open source software backed by offering services like:
Custom Development
Professional Support & Mentoring
Training
Server Tuning
Official Site:
Community:
Video Training:
Because of His grace, this project exists. If you don't like this, don't read it, it's not for you.
"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God." Romans 5:5
Security Hardening
Code Reviews
Source Code: https://github.com/coldbox/coldbox-platform
Bug Tracker: https://ortussolutions.atlassian.net/browse/COLDBOX
Social
Facebook: https://www.facebook.com/coldboxplatform
All the major information about ColdBox Releases
ColdBox is maintained under the Semantic Versioning guidelines as much as possible. Releases will be numbered in the following format:
And constructed with the following guidelines:
Breaking backward compatibility bumps the major (and resets the minor and patch)
New additions without breaking backward compatibility bump the minor (and resets the patch)
Bug fixes and misc changes bump the patch
For all ColdBox releases, updates are provided for 12 months, and security fixes are provided for 2 years after the next major release.
If you need professional support, please contact .
In this section, you will find the release notes and links for each version's documentation. If you are looking for the release notes of previous major versions, use the version switcher at the top left of this documentation book.
<major>.<minor>.<patch>Version 3.0 - March 2011
Version 2.0 - April 2007
Version 1.0 - June 2006
8.x
2025
2026
2027
7.x
2023
2024
2025
6.x
2022
2023
2024
Learn about the authors of ColdBox and how to support the project.
The source code for this book is hosted on GitHub: https://github.com/ortus-docs/coldbox-docs. You can freely contribute to it and submit pull requests. The contents of this book are copyrighted by Ortus Solutions, Corp and cannot be altered or reproduced without the author's consent. All content is provided "As-Is" and can be freely distributed.
The majority of code examples in this book are done in cfscript.
The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL - http://www.ortussolutions.com/products/commandbox
Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc.
ColdBox, CommandBox, FORGEBOX, TestBox, ContentBox, and Ortus Solutions are all trademarks and copyrights of Ortus Solutions, Corp.
The information in this book is distributed “as is” without warranty. The author and Ortus Solutions, Corp shall not have any liability to any person or entity concerning loss or damage caused or alleged to be caused directly or indirectly by the content of this training book, software, and resources described in it.
We highly encourage contributions to this book and our open-source software. The source code for this book can be found in our where you can submit pull requests.
10% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - . So please donate and purchase the printed version of this book, every book sold can help a child for almost 2 months.
Shalom Children’s Home () is one of the ministries that are dear to our hearts located in El Salvador. During the 12-year civil war that ended in 1990, many children were left orphaned or abandoned by parents who fled El Salvador. The Benners saw the need to help these children and received 13 children in 1982. Little by little, more children came on their own, churches and the government brought children to them for care, and the Shalom Children’s Home was founded.
Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education, and life skills training in a Christian environment. The home is supported by a child sponsorship program.
We have personally supported Shalom for over 6 years now; it is a place of blessing for many children in El Salvador who either has no families or have been abandoned. This is a good earth to seed and plant.
Discover the power of ColdBox 8.0.0
The best way to contribute to ColdBox
Hola amigo! I'm excited that you are interested in contributing to ColdBox, CacheBox, LogBox, and/or WireBox. Before submitting your contribution, please make sure to take a moment and read through the following guidelines:
This project is open source, and as such, the maintainers give their free time to build and maintain the source code held within. They make the code freely available in the hope that it will be of use to other developers and/or businesses. Please be considerate towards maintainers when raising issues or presenting pull requests. We all follow the Golden Rule: Do to others as you want them to do to you.
ColdBox 8.0.0 introduces groundbreaking features like BoxLang Prime integration, Virtual Thread Executors, enhanced AI-powered error handling, and a completely revamped developer experience. Whether you're building REST APIs, full-stack web applications, or microservices, this release has something exciting for every CFML developer.
🔥 BoxLang Prime - Native BoxLang module with BoxLang compilation and optimization (bx-coldbox)
⚡ Virtual Thread Executors - Modern async programming support
🤖 AI-Enhanced Whoops Experience - Intelligent error diagnostics
🎨 Enhanced Developer Tools - Updated CLI, VSCode extension, and templates
🔧 CacheBox Updates - Better performance and BoxLang integration
🌐 Modern Templates - New BoxLang and Modern application templates
🧹 Legacy Cleanup - Removal of deprecated features for a cleaner codebase
ColdBox 8.0.0 supports the following CFML engines:
⚡ BoxLang 1.0.0+ (with native compilation support!)
📦 Adobe ColdFusion 2023+
🔥 Lucee 5+
🚨 Important: Adobe ColdFusion 2021 support has been dropped in this release. Please upgrade to CF 2023 or newer for continued support.
ColdBox documentation is now accessible via the Model Context Protocol (MCP)! Connect AI assistants like Claude, GitHub Copilot, and other MCP-compatible tools directly to the comprehensive ColdBox documentation for instant access to language references, framework features, and best practices.
https://coldbox.ortusbooks.com/~gitbook/mcp
https://cachebox.ortusbooks.com/~gitbook/mcp
https://logbox.ortusbooks.com/~gitbook/mcp
https://wirebox.ortusbooks.com/~gitbook/mcp
This enables developers to:
🔍 Search ColdBox documentation semantically from within AI assistants
💡 Get instant answers about BIFs, components, and framework features
📖 Access code examples and best practices without leaving your workflow
🤖 Enhance AI-assisted ColdBox development with authoritative documentation
In this release, we now introduce a new version of ColdBox specifically optimized and pre-compiled for BoxLang. Introducing bx-coldbox which you can install via CommandBox or the BoxLang module installer:
This version of ColdBox is pre-compiled with BoxLang and optimized for performance. It also includes the new BoxLang Prime features for CacheBox, LogBox, and WireBox. It installs into the engine itself instead of your application. This means, you can have ColdBox available to any BoxLang application without needing to install it in each app. It also means that you can leverage the native BoxLang compilation for better performance, startup times, and security.
Say hello to BoxLang PRIME — the next evolution of the ColdBox Platform. For the first time ever, you can build and run your ColdBox applications natively in BoxLang — no CFML Compatibility Module required!
BoxLang PRIME delivers full native integration across CacheBox, LogBox, and WireBox, unlocking a new era of speed, security, and seamless performance.
🔥 Experience faster startups.
⚡ Harness native BoxLang compilation.
🧠 Build smarter, lighter, and more future-ready ColdBox apps.
Combined with the new bx-coldbox package, BoxLang PRIME is the ultimate way to build modern JVM applications.
Please Note: Not all modules are yet BoxLang PRIME compatible. We are working hard to bring you full compatibility across the entire ColdBox ecosystem. Stay tuned for updates!
We’ve been hard at work on something truly game-changing: soon, you’ll be able to run your ColdBox applications as fully functional desktop apps with BoxLang Desktop.
That’s right — build cross-platform desktop experiences powered by ColdBox and BoxLang, all with the same productivity and elegance you already love. With the introduction of bx-coldbox and ColdBox BoxLang PRIME support, you can now leverage the full power of ColdBox in desktop environments.
🖥️ One language.
🌍 Any platform.
⚡ Endless possibilities.
Stay tuned, this is coming real soon.
The ColdBox CLI has been completely revamped 🎨 to support ColdBox 8 applications with enhanced features:
🆕 Migration Creation - Generate database migrations effortlessly
🐳 Docker Support - Streamlined Docker integration for your applications
⚡ Vite Support - Modern frontend tooling integration
🧪 API Testing Tools - Built-in testing capabilities
📋 Project Scaffolding - Quick application setup
🔧 Enhanced Generators - More code generation options
🤖 AI Integration - Leverage AI for smarter code suggestions
📚 Documentation - It has also been completely documented here: .
Install it via CommandBox:
What's also powerful is that using our new application templates the CLI can now configure your application for:
Docker Creation and support
Vite support for modern frontend development
Maven support for Java dependencies
REST Only applications
Much More
All application templates now come with AI assistance via our VSCode BoxLang extension and copilot instructions. You can get code suggestions, event handler code generation, and more. Just install the BoxLang VSCode Extension and start coding: https://marketplace.visualstudio.com/items?itemName=ortus-solutions.vscode-boxlang-developer-pack
All of our modules, and ColdBox core have been updated with copilot instructions to help you get the most out of your AI assistants.
We have been working on these new layouts and experimenting with them for over 2 years now. We are excited to announce that they are now production ready and available for you to use. These new layouts embrace modern development practices, non-root based architectures, and of course BoxLang.
They are more intuitive, easier to understand, and provide a better developer experience than the traditional flat put everything in the webroot approach. They also embrace modern frontend tooling like Vite, TailwindCSS, and more. Icing on the cake is that now if you are using BoxLang, we include a Build.bx that will allow you to build, validate, pre-compile and package your application for deployment.
We will also be introducing soon the new coldbox deploy command that will allow you to deploy your application to any Ortus Deployable Server or any CommandBox server. Stay tuned!
Here are our new default templates:
🔥 BoxLang Template - Native BoxLang ColdBox applications https://github.com/coldbox-templates/boxlang
🎨 Modern Template - Non-root based architecture (now operational!) https://github.com/coldbox-templates/modern
Pure BoxLang Power - Experience the first native BoxLang ColdBox template designed from the ground up for modern JVM applications!
What You Get:
🚀 Native BoxLang compilation with Build.bx for lightning-fast deployments
🎯 Zero-config Docker support with optimized runtime containers
⚡ Vite integration for modern frontend development with hot-reload
🧪 Built-in testing suite with TestBox integration and CI/CD workflows
🤖 AI-first development with VSCode BoxLang extension and copilot instructions
📦 Maven support for Java dependencies and enterprise builds
🛡️ Security by design with non-root architecture and DevContainer support
🎨 REST-ready with dedicated API structure and OpenAPI documentation
Perfect for: Greenfield projects, microservices, desktop applications, and teams ready to embrace the future of JVM development.
🔥 Key Architecture Benefits:
Security First: Application code is completely isolated from web access
Modern Tooling: Vite for frontend, Maven for dependencies, Docker for deployment
BoxLang Native: Pure .bx and .bxm files with native compilation support
Zero Configuration: Everything works out of the box with sensible defaults
Production-Ready Excellence - Built for teams who demand enterprise-level structure without sacrificing developer productivity. This template brings years of production experience into a clean, maintainable architecture.
What You Get:
🏗️ Non-root security architecture keeping your application safe from web-based attacks
🐳 Complete Docker ecosystem with multi-stage builds and production optimization
🔄 Database migration support with CF Migrations for seamless deployments
📊 Comprehensive monitoring with structured logging and application metrics
🧩 Modular design with clear separation of concerns across all layers
🛠️ Enterprise tooling with CF Config, formatting, and linting pre-configured
🚀 CI/CD ready with GitHub Actions for testing, building, and deployment
📱 Frontend flexibility supporting both traditional CFML views and modern JS frameworks
Perfect for: Enterprise applications, legacy modernization, teams requiring strict security compliance, and applications with complex deployment requirements.
🎯 Enterprise Architecture Benefits:
Separation of Concerns: Clean MVC with modular HMVC capabilities
Database Migrations: Version-controlled schema changes with CF Migrations
Docker Ready: Production-optimized containers with development compose
Enterprise Tooling: CF Config, linting, formatting, and CI/CD integration
We have completely revamped the ColdBox Whoops experience to include AI capabilities, enhanced stack traces, improved UI and so much more. This means that when an error happens, you will get not only the stack trace, but also AI generated suggestions on how to fix it, links to documentation, and more.
ColdBox 8.0.0 introduces native support for Virtual Thread Executors, bringing modern asynchronous programming capabilities to your CFML applications. Build high-performance, non-blocking applications with ease.
Experience the future of debugging with our AI-powered error handling. Get intelligent suggestions, context-aware debugging tips, and smarter error diagnosis to solve issues faster than ever.
🎯 Delegates - Reusable component behaviors for cleaner code
⏱️ Lazy Properties - On-demand property initialization for better performance
👀 Property Observers - React to property changes automatically
💾 Transient Request Cache - Optimized request-scoped caching
🎨 Pretty JSON Output - Beautiful, readable JSON in your logs
🔒 Closure-based Logging - Performance-optimized logging with lambda functions
🔧 Better Exception Handling - Enhanced error serialization and reporting
Native BoxLang Prime integration across the entire platform, bringing:
⚡ Enhanced Performance - Native compilation benefits
🔧 Better Integration - Seamless BoxLang ecosystem support
📦 Optimized Distribution - Engine-level installation options
📅 Enhanced Scheduled Tasks - Better task management and scheduling
🛣️ Improved Routing - Enhanced path handling and URL generation
🧪 Testing Enhancements - Better testing tools and utilities
🎨 View Improvements - Enhanced rendering capabilities
ColdBox 8.0.0 removes deprecated features to keep the codebase modern and maintainable:
Removed Client Flash - Legacy insecure storage method
Updated BeanPopulator - Replaced with ObjectPopulator
Router Modernization - Removed deprecated routing methods
Environment Variable Handling - Enhanced Env delegate support
COLDBOX-1332 Virtual Thread executors support
COLDBOX-1333 Make the build Executor public, for devs that just want executors built and NOT registered
COLDBOX-1334 Executors more stats for issue detection
COLDBOX-1341 New Whoops Experience with AI Capabilities
COLDBOX-1331 Add ability to ignore or include RC keys when caching events
COLDBOX-1343 Incorporate appName into lock names to give better uniqueness
COLDBOX-1360 Bootstrap was not returning false or true on the right location for onRequestStart
COLDBOX-1328 Improve error message for Module Settings in ColdBox DSL
COLDBOX-1329 Module Config override convention depends on file system case sensitivity
COLDBOX-1330 missing replacement of double // on layouts/views on new rendering schemas
COLDBOX-1338 RequestContext StatusCode Should Default to 200
COLDBOX-1340 ColdboxProxy throws "invalid call of the function ReplaceNoCase"
COLDBOX-1345 NotAuthorized catch in RestHandler should return onAuthorizationFailure - not onAuthenticationFailure
COLDBOX-1350 DateTimeHelper timeUnitToSeconds needs to ignore converting seconds if chosen
COLDBOX-1359 Regression view layout relative app mapping paths
COLDBOX-1361 Routing service was not evaluating the coldbox web mapping when public facing app is in another folder than the coldbox app
COLDBOX-1346 Client Flash removal as legacy
COLDBOX-1352 BeanPopulator finally removed
COLDBOX-1353 Util: getSystemSetting, getSystemProperty, getEnv() removed in favor to the Env Delegate
COLDBOX-1354 RequestContext removed methods: isSES(), setSESEnabled()
COLDBOX-1355 Remove ColdBox 4 compat : getModulesRoutingTable(), includeRoutes() in the Router.cfc
COLDBOX-1356 Removeal of Router.with() and endWith() in favor of the group() closures.
COLDBOX-1357 Router addRoute() matchVariables argument finally removed
COLDBOX-1358 ProcessState in the InterceptorService is now finally removed
CACHEBOX-91 BoxLang Prime
CACHEBOX-90 CacheBox CFProvider Only Works with EhCache
LOGBOX-84 BoxLang Prime
LOGBOX-83 Add new LogBox configuration option to disallow serializing complex objects: serializeExtraInfo
WIREBOX-156 BoxLang prime
WIREBOX-157 getCacheBoxConfig() on WireBox Binder removed after deprecation
WIREBOX-158 Binder.getProperty() `default` Argument Removed
As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
Participants will be tolerant of opposing views.
Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions not aligned with this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
When interpreting the words and actions of others, participants should always assume good intentions. Emotions cannot be derived from textual representations.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
Each of the main standalone frameworks in ColdBox has separate locations for submitting bug reports. Please also ensure that if you submit a pull request, you link it to the appropriate issue.
ColdBox Core: https://ortussolutions.atlassian.net/browse/COLDBOX
If you file a bug report, your issue should contain a title, a clear description of the issue, a way to replicate the issue, and any support files we might need to replicate your issue. The goal of a bug report is to make it easy for yourself - and others - to replicate the bug and develop a fix for it. All issues that do not contain a way to replicate will not be addressed.
If you have questions about usage, professional support, or just ideas to bounce off the maintainers, please do not create an issue. Leverage our support channels first.
Ortus Community Discourse: https://community.ortussolutions.com/c/communities/coldbox/13
Box Slack Team: http://boxteam.ortussolutions.com/
Professional Support: https://www.ortussolutions.com/services/support
The master branch is just a snapshot of the latest stable release. All development should be done in dedicated branches. Do not submit PRs against the master branch. They will be closed.
All pull requests should be sent against the development branch or the LTS version branch releases/v{version}
It's OK to have multiple small commits as you work on the PR - GitHub will automatically squash it before merging.
Make sure all local tests pass before submitting the merge.
Please make sure all your pull requests have companion tests.
Please link the Jira issue in your PR title when sending the final PR
If you discover a security vulnerability, please email the development team at [email protected] and make sure you report it to the #security channel in our Box Team Slack Channel. All security vulnerabilities will be promptly addressed.
We have added all the necessary information to develop on ColdBox in our readme collaboration area and our tests readme so you can set up the database to test against.
Please make sure your code runs on the following Supported CFML Engines:
BoxLang 1+
Lucee 5+
Adobe ColdFusion 2023+
We are big on coding styles and have included a .cfformat.json in the root of the project so that you can run the formatting tools and CommandBox scripts:
We recommend that anytime you hack on the core, you start the format watcher (box run-script format:watch). This will monitor your changes and auto-format your code for you.
You can also see the Ortus Coding Standards you must follow here: https://github.com/Ortus-Solutions/coding-standards.
All CFCs are self-documenting, and we leverage DocBox to document the entire software. All functions must be properly documented using the DocBox syntax: https://docbox.ortusbooks.com/getting-started/annotating-your-code
You can support ColdBox and all of our Open Source initiatives at Ortus Solutions by becoming a Patreon. You can also get lots of goodies and services depending on the level of contributions.
Thank you to all the people who have already contributed to ColdBox! We: heart: : heart: : heart: love you!
Made with contributors-img
Author biographies of the ColdBox Platform
Luis Majano is a Computer Engineer, and published author that has been creating software since the year 2000. He was born in San Salvador, El Salvador in the late 70s, during a period of economical instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he studied and completed his Bachelor of Science in Computer Engineering at Florida International University.
He is the founder and CEO of Ortus Solutions, a consulting firm specializing in web development, ColdFusion (CFML), Java development, and all open-source professional services under the ColdBox, CommandBox, and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, TestBox, LogBox, and anything “BOX”, and contributes to over 250 open-source projects. He has a passion for learning and mentoring developers so they can succeed with sustainable software practices and the usage and development of open-source software. You can read his blog at
Luis has a passion for Jesus, tennis, golf, volleyball, and anything electronic. Random Author Facts:
He played volleyball in the Salvadorean National Team at the tender age of 17
The Lord of the Rings and The Hobbit are his favorite books (Geek!)
His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)
Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!
“Trust in the LORD with all your heart, and do not lean on your own understanding.” – Proverbs 3:5
Jorge is an Industrial and Systems Engineer born in El Salvador. After finishing his Bachelor studies at the Monterrey Institute of Technology and Higher Education , Mexico, he went back to his home country where he worked as the COO of. In 2012 he left El Salvador and moved to Switzerland in pursuit of the love of his life. He married her and today he resides in Basel with his lovely wife Marta and their daughter Sofía.
Jorge started working as project manager and business developer at Ortus Solutions, Corp. in 2013, . At Ortus he fell in love with software development and now enjoys taking part on software development projects and software documentation! He is a fellow Christian who loves to play the guitar, worship and rejoice in the Lord!
Therefore, if anyone is in Christ, the new creation has come: The old has gone, the new is here! 2 Corinthians 5:17
Brad grew up in southern Missouri where he systematically disassembled every toy he ever owned which occasionally led to unintentional shock therapy (TVs hold a charge long after they've been unplugged, you know) After high school he majored in Computer Science with a music minor at (Olathe, KS). Today he lives in Kansas City with his wife and three girls where he still disassembles most of his belongings (including automobiles) just with a slightly higher success rate of putting them back together again.) Brad enjoys church, all sorts of international food, and the great outdoors.
Brad has been programming CFML for 12+ years and has used every version of CF since 4.5. He first fell in love with ColdFusion as a way to easily connect a database to his website for dynamic pages. Brad blogs at () and likes to work on solder-at-home digital and analog circuits with his daughter as well as building projects with Arduino-based microcontrollers.
Brad's CommandBox Snake high score is 141.
# CommandBox
box install bx-coldbox
# BoxLang Module
install-bx-module bx-coldbox ██████╗ ██████╗ ██╗ ██████╗ ██████╗ ██████╗ ██╗ ██╗ ██████╗██╗ ██╗
██╔════╝██╔═══██╗██║ ██╔══██╗██╔══██╗██╔═══██╗╚██╗██╔╝ ██╔════╝██║ ██║
██║ ██║ ██║██║ ██║ ██║██████╔╝██║ ██║ ╚███╔╝█████╗██║ ██║ ██║
██║ ██║ ██║██║ ██║ ██║██╔══██╗██║ ██║ ██╔██╗╚════╝██║ ██║ ██║
╚██████╗╚██████╔╝███████╗██████╔╝██████╔╝╚██████╔╝██╔╝ ██╗ ╚██████╗███████╗██║
╚═════╝ ╚═════╝ ╚══════╝╚═════╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ╚═════╝╚══════╝╚═╝install coldbox-cli
coldbox --help# Use the new boxlang template
coldbox create app MyBoxLangApp
# Use the new modern template
coldbox create app MyBoxLangApp skeleton=modern
coldbox create app MyBoxLangApp --cfmlMyBoxLangApp/
├── 📁 app/ # 🔒 Secure ColdBox App
│ ├── config/ # Configuration
│ ├── handlers/ # Event handlers (controllers)
│ ├── interceptors/ # Interceptors
│ ├── layouts/ # Layout templates
│ ├── models/ # Business logic layer
│ ├── modules/ # Custom Modules
│ ├── views/ # Presentation templates
│ └── layouts/ # Page layout templates
├── 📁 modules/ # 🗳️ CommandBox Tracked Modules
├── 📁 public/ # 🌐 Web-accessible directory
│ ├── index.bxm # Application entry point
│ ├── includes/ # CSS, JS, images
│ └── Application.bx # Public bootstrap
├── 📁 resources/ # 🛠️ Development assets
│ └── database/migrations/ # Database version control
├── 📁 runtime/ # 🏃 Runtime libraries & logs
├── 📁 tests/ # 🧪 Testing suite
└── Build.bx # 🚀 BoxLang build automation
└── box.json # CommandBox project descriptor
└── server.json # CommandBox server descriptor
└── pom.xml # Maven project descriptorMyModernApp/
├── 📁 app/ # 🔒 Secure ColdBox Application (above webroot)
│ ├── config/ # Configuration
│ ├── handlers/ # Event handlers (controllers)
│ ├── interceptors/ # Interceptors
│ ├── layouts/ # Layout templates
│ ├── models/ # Business logic layer
│ ├── modules/ # Custom Modules
│ ├── views/ # Presentation templates
│ └── layouts/ # Page layout templates
├── 📁 public/ # 🌐 Web-accessible directory
│ ├── index.cfm # Application entry point
│ └── includes/ # Static assets (CSS, JS, images)
├── 📁 docker/ # 🐳 Container orchestration
│ ├── Dockerfile # Multi-stage production builds
│ └── docker-compose.yml # Development environment
├── 📁 resources/ # 🗃️ Application resources
│ └── database/migrations/ # Database version control
├── 📁 lib/ # 📚 Framework libraries
│ ├── coldbox/ # ColdBox framework files
│ └── testbox/ # Testing framework
└── 📁 tests/ # 🧪 Comprehensive test suite
└── box.json # CommandBox project descriptor
└── server.json # CommandBox server descriptor
└── pom.xml # Maven project descriptor# Format everything
box run-script format
# Start a watcher, type away, save and auto-format for you
box run-script format:watch
He has of late (during old age) become a fan of organic gardening.
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 or removed features.
ColdFusion 2018-2021 support has been dropped. Adobe doesn't support them anymore, so neither do we.
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
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.
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.
The following methods were removed in preference to the Environment Delegate class: coldbox.system.core.delegates.Env.
default Argument RemovedThe default argument was deprecated in ColdBox 6 and has now been removed. Please use defaultValue instead.
The getCacheBoxConfig() method was deprecated in ColdBox 6 and has now been removed. Please use getCacheBox() instead.
The following methods were removed from the RequestContext class. These methods were deprecated in ColdBox 7.
isSES()
setSESEnabled()
The getModulesRoutingTable() method was deprecated in ColdBox 7 and has now been removed. Please use getModuleRoutingTable() instead.
The includeRoutes() method was deprecated in ColdBox 6 and has now been removed. This was for cfm routers which are no longer in use.
The with() and endWith() methods were deprecated in ColdBox 7 and have now been removed. Please use the group() method with closures instead.
matchVariables Argument RemovedThe 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.
The setFullRewrites() method has been removed from the Router. This method was used to enable/disable SES URL rewrites but is no longer needed as SES routing is handled automatically.
The processState() method has been removed from the InterceptorService (). This method was deprecated and has now been completely removed.
Migration: Use the announce() method instead.
The following methods were deprecated in ColdBox 7 and will be removed in ColdBox 9.
renderView() -> use view()
renderLayout() -> use layout()
renderExternalView() -> use externalView()
newSchedule() -> use newTask()
The following instructions are designed to help AI assistants inspect and automatically upgrade ColdBox applications from version 7 to version 8.
When analyzing ColdBox applications for upgrade compatibility, check for these patterns:
Look for implementations extending deprecated interfaces:
Apply these replacements when upgrading code:
After applying automated changes, verify:
Engine Compatibility: Ensure minimum ColdFusion 2021+ or Lucee 5.3+
Test Coverage: Run existing test suites to validate functionality
Cache Providers: Test custom cache provider implementations
Module Compatibility: Verify all modules work with updated router methods
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
announceInterception() -> use announce()
populateModel() -> use populate()
Environment Variables: Ensure environment delegate usage works correctly
/**
* @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 );
}// 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 );
} );
// 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" }
)// Old way - removed
interceptorService.processState( "myEvent", data );
// New way - use announce()
interceptorService.announce( "myEvent", data );// Search for these deprecated patterns:
- extends="coldbox.system.cache.ICacheProvider"
- extends="coldbox.system.cache.IStats"// Search for BeanPopulator instantiation or injection:
- new coldbox.system.core.dynamic.BeanPopulator()
- property name="beanPopulator" inject="BeanPopulator"
- wirebox.getInstance( "BeanPopulator" )// Search for client flash scope references:
- flash.setFlash()
- flash.getFlash()
- flashScope="client"
- setNextEvent( flashScope="client" )// Search for deprecated util methods:
- getSystemSetting()
- getSystemProperty()
- getEnv()
// When found in non-Env delegate contexts// In WireBox binders, search for:
- .getProperty( default=
- .getCacheBoxConfig()// Search for these method calls:
- event.isSES()
- event.setSESEnabled()// Search for these router method calls:
- router.getModulesRoutingTable()
- router.includeRoutes()
- router.with()
- router.endWith()
- router.setFullRewrites()
- matchVariables argument in addRoute()// Search for deprecated InterceptorService method calls:
- interceptorService.processState()
- processState() // when called within interceptor context// Search for these method calls in handlers/interceptors:
- renderView()
- renderLayout()
- renderExternalView()
- announceInterception()
- populateModel()
- newSchedule() // in ScheduledExecutor context// 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"// Replace all instances of:
BeanPopulator
// With:
ObjectPopulator
// Replace injection:
inject="BeanPopulator"
// With:
inject="ObjectPopulator"// 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" )// Replace:
.getProperty( key, default=value )
// With:
.getProperty( key, defaultValue=value )
// Replace:
.getCacheBoxConfig()
// With:
.getCacheBox()// 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" }
)// Replace:
interceptorService.processState( "eventName", data )
// With:
interceptorService.announce( "eventName", data )
// Replace:
processState( "eventName", data )
// With:
announce( "eventName", data )// Replace deprecated methods:
renderView() -> view()
renderLayout() -> layout()
renderExternalView() -> externalView()
announceInterception() -> announce()
populateModel() -> populate()
newSchedule() -> newTask()// 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" )
