1 of 100

3.0.0-SNAPSHOT

INTRODUCTION

Getting Started

Install Wheels and get a local development server running

By far the quickest way to get started with Wheels is via CommandBox. CommandBox brings a whole host of command line capabilities to the CFML developer. It allows you to write scripts that can be executed at the command line written entirely in CFML. It allows you to start a CFML server from any directory on your machine and wire up the code in that directory as the web root of the server. What's more is, those servers can be either Lucee servers or Adobe ColdFusion servers. You can even specify what version of each server to launch. Lastly, CommandBox is a package manager for CFML. That means you can take some CFML code and package it up into a module, host it on ForgeBox.io, and make it available to other CFML developers. In fact we make extensive use of these capabilities to distribute Wheels plugins and templates. More on that later.

One module that we have created is a module that extends CommandBox itself with commands and features specific to the Wheels framework. The Wheels CLI module for CommandBox is modeled after the Ruby on Rails CLI module and gives similar capabilities to the Wheels developer.

Install CommandBox

The first step is to get CommandBox downloaded and running. CommandBox is available for Windows, Mac & Linux, and can be installed manually or using one of the respective package managers for each OS. You can use Chocolatey on Windows, Homebrew on MacOS, or Yum/Apt on Linux depending on your flavor of Linux. Please follow the instructions on how to install CommandBox on your particular operating system. At the end of the installation process you want to make sure the box command is part of your system path so you can call the command from any directory on your system.

Once installed, you can either double-click on the box executable which opens the CommandBox shell window, or run box from a CMD window in Windows, Terminal window in MacOS, or shell prompt on a Linux server. Sometimes you only want to call a single CommandBox command and don't need to launch a whole CommandBox shell window to do that, for these instances you can call the CommandBox command directly from your default system terminal window by prefixing the command with the box prefix.

So to run the CommandBox version command you could run box version from the shell or you could launch the CommandBox shell and run version inside it.

box version

version

This is a good concept to grasp, cause depending on your workflow, you may find it easier to do one versus the other. Most of the commands you will see in these CLI guides will assume that you are entering the command in the actual CommandBox shell so the box prefix is left off.

Install the wheels-cli CommandBox Module

Okay, now that we have CommandBox installed, let's add the Wheels CLI module.

install wheels-cli

Installing this module will add a number of commands to your default CommandBox installation. All of these commands are prefixed by the wheels name space. There are commands to create a brand new Wheels application or scaffold out sections of your application. We'll see some of these commands in action momentarily.

Start a new Application using the Wizard

To install a new application using version 3.0, we can use the new application wizard and select Bleeding Edge when prompted to select the template to use.

wheels new

Start a New Application Using the Command Line

Now that we have CommandBox installed and extended it with the Wheels CLI module, let's start our first Wheels app from the command line. We'll look at the simplest method for creating a Wheels app and starting our development server.

wheels generate app myApp server start

A few minutes after submitting the above commands a new browser window should open up and display the default Wheels congratulations screen.

So what just happened? Since we only passed the application name myApp to the wheels generate app command, it used default values for most of its parameters and downloaded our Base template (wheels-base-template) from ForgeBox.io, then downloaded the framework core files (wheels.dev) from ForgeBox.io and placed it in the vendor/wheels directory, then configured the application name and reload password, and started a Lucee server on a random port.

A Word About Command Aliases

CommandBox commands have the capability to be called by multiple names or aliases. The command above wheels generate app can also be initiated by typing wheels g app. In fact g is an alias for generate so wherever you see a command in the CLI documentation that has generate in it you can substitute g instead.

In addition to shortening generate to g, aliases can completely change the name space as well. A command that you haven't seen yet is the wheels generate app-wizard command. This command guides the user through a series of menu options, building up all the parameters needed to customize the start of a new Wheels project. You're likely to use the wizard when starting a new Wheels application so it's good to become familiar with it.

This command has the normal alias referenced above at wheels g app-wizard but it also has an additional alias at wheels new which is the command more prevalent in the Rails community. So the three commands wheels generate app-wizard, wheels g app-wizard, and wheels new all call the same functionality which guides the user though a set of menus, collecting details on how to configure the desired app. Once all the parameters have been gathered, this command actually calls the wheels generate app command to create the actual Wheels application.

This Getting Started guide has taken you from the very beginning and gotten you to the point where you can go into any empty directory on your local development machine and start a Wheels project by issuing a couple of CLI commands. In later guides we'll explore these options further and see what else the CLI can do for us.

Running Local Development Servers

Starting a local development server

With CommandBox, we don't need to have Lucee or Adobe ColdFusion installed locally. With a simple command, we can make CommandBox go and get the CFML engine we've requested, and quickly create a server running on Undertow. Make sure you're in the root of your website, and then run:

server start

The server will then start on a random port on 127.0.0.1 based the configuration from the server.json file that is in the root of your application that comes with wheels. We can add various options to server.json to customize our server. Your default server.json will look something like this:

In this server.json file, the server name is set to wheels, meaning I can now start the server from any directory by simply calling start myApp. We don't have any port specified, but you can specify any port you want. Lastly, we have URL rewriting enabled and pointed the URL rewrite configuration file to public/urlrewrite.xml, which is included starting from Wheels 2.x.

Using custom host names

You can also specify hosts other than localhost: there's a useful CommandBox module to do that () which will automatically create entries in your hosts file to allow for domains such as myapp.local running on port 80. You can install it via install commandbox-hostupdater when running the box shell with administrator privileges.

Controlling local servers

Obviously, anything you start, you might want to stop. Servers can be stopped either via right/ctrl clicking on the icon in the taskbar, or by the stop command. To stop a server running in the current directory issue the following:

server stop

You can also stop a server from anywhere by using its name:

server stop myApp

If you want to see what server configurations exist on your system and their current status, simply do server list

server list

To remove a server configuration from the list, you can use server forget myapp. Note the status of the servers on the list are somewhat unreliable, as it only remembers the last known state of the server: so if you start a server and then turn off your local machine, it may still remember it as running when you turn your local machine back on, which is why we recommend the use of force: true in the server.json file.

Specifying different CF engines

By default, CommandBox will run Lucee (version 6.x at time of writing). You may wish to specify an exact version of Lucee, or use Adobe ColdFusion. We can do this via either setting the appropriate cfengine setting in server.json, or at runtime with the cfengine= argument.

Start the default engine

CommandBox> start

Start the latest stable Lucee 5.x engine

CommandBox> start cfengine=lucee5

Start a specific engine and version

CommandBox> start [email protected]

Start the most recent Adobe server that starts with version "11"

CommandBox> start cfengine=adobe@11

Start the most recent adobe engine that matches the range

CommandBox> start cfengine="adobe@>9.0 <=11"

Or via server.json

CFIDE / Lucee administrators

The default username and password for all administrators is admin & commandbox

You can of course run multiple servers, so if you need to test your app on Lucee 5.x, Lucee 6.x and Adobe 2018, you can just start three servers with different cfengine= arguments!

Watch out

CommandBox 5.1 required to install dependencies easily

By default, the Lucee server that CommandBox starts includes all the essential Lucee extensions you need, but if need to minimize the size of the Lucee instance you launch, then you can use Lucee-Light by specifying cfengine=lucee-light in your server.json file. Wheels can run just fine on lucee-light (which is after all, Lucee, minus all the extensions) but at a minimum, requires the following extensions to be installed as dependencies in your box.json. Please note you may have to add any drivers you need for your database to this list as well.

Once added to your box.json file, while the server is running, just do box install, which will install the dependencies, and load them into the running server within 60 seconds.

Alternatively you can download the extensions and add them manually to your server root's deploy folder (i.e \WEB-INF\lucee-server\deploy)

Tutorial: Wheels, AJAX, and You

Using Wheels to develop web applications with AJAX features is a breeze. You have several options and tools at your disposal, which we'll cover in this chapter.

Wheels was designed to be as lightweight as possible, so this keeps your options fairly open for developing AJAX features into your application.

While there are several flavors of JavaScript libraries out there with AJAX support, we will be using the in this tutorial. Let's assume that you are fairly familiar with the basics of jQuery and know how to set it up.

For this tutorial, let's create the simplest example of all: a link that will render a message back to the user without refreshing the page.

A Simple Example

In this example, we'll wire up some simple JavaScript code that calls a Wheels action asynchronously. All of this will be done with basic jQuery code and built-in Wheels functionality.

First, let's make sure we've got an appropriate route setup. It might be you're still using the default wildcard() route which will create some default GET routes for the controller/action pattern, but we'll add a new route here just for practice. We are going to create a route named sayHello and direct it to the hello action of the say controller. There are two ways you could write this code a long hand method specifying the controller and action separately as well as a short hand method that combines the two into a single parameter.

The longhand way would look like:

The shorthand method would look like:

You can decide which method you prefer. Both sets of code above are equivalent.

Then, let's create a link to a controller's action in a view file, like so:

That piece of code by itself will work just like you expect it to. When you click the link, you will load the hello action inside the say controller.

But let's make it into an asynchronous request. Add this JavaScript (either on the page inside script tags or in a separate .js file included via ):

With that code, we are listening to the click event of the hyperlink, which will make an asynchronous request to the hello action in the say controller. Additionally, the JavaScript call is passing a URL parameter called format set to json.

Note that the success block inserts keys from the response into the empty h1 and p blocks in the calling view. (You may have been wondering about those when you saw the first example. Mystery solved.)

The last thing that we need to do is implement the say/hello action. Note that the request expects a dataType of JSON. By default, Wheels controllers only generate HTML responses, but there is an easy way to generate JSON instead using Wheels's and functions:

In this controller's config() method, we use the function to indicate that we want all actions in the controller to be able to respond with the data in HTML or JSON formats. Note that the client calling the action can request the type by passing a URL parameter named format or by sending the format in the request header.

The call to in the hello action takes care of the translation to the requested format. Our JavaScript is requesting JSON, so Wheels will format the greeting struct as JSON automatically and send it back to the client. If the client requested HTML or the default of none, Wheels will process and serve the view template at app/views/say/hello.cfm. For more information about and , reference the chapter on .

Lastly, notice the lines where we're setting greeting["message"] and greeting["time"]. Due to the case-insensitive nature of ColdFusion, we recommend setting variables to be consumed by JavaScript using bracket notation like that. If you do not use that notation (i.e., greetings.message and greetings.time instead), your JavaScript will need to reference those keys from the JSON as MESSAGE and TIME (all caps). Unless you like turning caps lock on and off, you can see how that would get annoying after some time.

Assuming you already included jQuery in your application and you followed the code examples above, you now have a simple AJAX-powered web application built on Wheels. After clicking that Alert me! link, your say controller will respond back to you the serialized message via AJAX. jQuery will parse the JSON object and populate the h1 and pwith the appropriate data.

AJAX in Wheels Explained

That is it! Hopefully now you have a clearer picture on how to create AJAX-based features for your web applications.

Manual Installation

Instructions for installing Wheels on your system.

Installing Wheels is so simple that there is barely a need for a chapter devoted to it. But we figured we'd better make one anyway in case anyone is specifically looking for a chapter about installation.

So, here are the simple steps you need to follow to get rolling on Wheels...

Manual Installation

1. Download Wheels

You have 2 choices when downloading Wheels. You can either use the latest official release of Wheels, or you can take a walk on the wild side and go with the latest committed source code in our Git repository.

The latest official releases can always be found in the Releases section of GitHub, and the Git repository is available at our GitHub repo.

In most cases, we recommend going with the official release because it's well documented and has been through a lot of bug testing. Only if you're in desperate need of a feature that has not been released yet would we advise you to go with the version stored in the Git master branch.

Let's assume you have downloaded the latest official release. (Really, you should go with this option.) You now have a .zip file saved somewhere on your computer. On to the next step...

2. Setup the Website

Getting an empty website running with Wheels installed is an easy process if you already know your way around IIS or Apache. Basically, you need to create a new website in your web server of choice and unzip the contents of the file into the root of it.

In case you're not sure, here are the instructions for setting up an empty Wheels site that can be accessed when typing localhost in your browser. The instructions refer to a system running Windows Server 2003 and IIS, but you should be able to follow along and apply the instructions with minor modifications to your system. (See Requirements for a list of tested systems).

Create a new folder under your web root (usually C:\Inetpub\wwwroot) named wheels_site and unzip the Wheels .zip file into the root of it.
Create a new website using IIS called Wheels Site with localhost as the host header name and C:\Inetpub\wwwroot\mysite as the path to your home directory.

If you want to run a Wheels-powered application from a subfolder in an existing website, this is entirely possible, but you may need to get a little creative with your URL rewrite rules if you want to get pretty URLs--it will only work out of the box on recent versions of Apache. (Read more about this in the URL Rewriting chapter.)

3. Setup the Database (Optional)

Create a new database in MySQL, PostgreSQL, Microsoft SQL Server, or H2 and add a new data source for it in the ColdFusion/Lucee Administrator, just as you'd normally do. Now open up /config/settings.cfm and call set(dataSourceName="") with the name you chose for the data source.

If you don't want to be bothered by opening up a Wheels configuration file at all, there is a nice convention you can follow for the naming. Just name your data source with the same name as the folder you are running your website from (mysite in the example above), and Wheels will use that when you haven't set the dataSourceName setting using the Set() function.

4. Test It

When you've followed the steps above, you can test your installation by typing http://localhost/ (or whatever you set as the host header name) in your web browser. You should get a "Congratulations!" page.

That's it. You're done. This is where the fun begins!

Screencasts

Tutorials, demonstrations, and presentations about the ColdFusion on Wheels framework.

Wheels 2.x

Create a basic CRUD interface in Wheels 2.x

Create a basic JSON API in Wheels 2.x

Routing in Wheels 2.x - Part 1

Routing in Wheels 2.x - Part 2

Introduction to Unit Testing in Wheels 2.x

Unit Testing Controllers in Wheels 2.x

Wheels 1.x

Please note that all the webcasts below were created with Wheels 1.x in mind, and are listed here as they might still be useful to those starting out.

CRUD series

Learn about basic create operations when building standard CRUD functionality in Wheels

Learn about basic read operations when building standard CRUD functionality in Wheels

Chris Peters demonstrates updating data in a simple CRUD Wheels application

Learn how simple it is to delete records in a basic CRUD application using Wheels

Chris Peters starts the webcast series by demonstrating how to set up ColdFusion on Wheels

Chris Peters demonstrates how to bind a Wheels model object to a form through the use of form helpers

Chris Peters adds data validation to the user registration form

Chris Peters finishes the "success" portion of the registration functionality by adding a success message to the Flash and redirecting the user to their home screen

Chris Peters teaches you about more validation options and how you can add them to the registration form quickly and easily

Chris Peters stylizes form markup globally using a Wheels feature called global helpers

Learn how to set up simple user authentication on a website by using a Wheels feature called filters

Learn the mechanics of reading a single record from the database and displaying its data in the view

Creating custom URL patterns is a breeze in ColdFusion on Wheels

Learn how to fetch multiple records from your model with findAll() and then display them to the user using ColdFusion on Wheels

Learn how to factor out logic in your view templates into custom helper functions in ColdFusion on Wheels

Chris Peters demonstrates joining data together with model associations using ColdFusion on Wheels

All it takes to offer pagination is two extra arguments to findAll() and a call to a view helper called paginationLinks()

Learn how to use the provides() and renderWith() functions to automatically serialize data into XML, JSON, and more

Other

Peter Amiri walks you through setting up a "Hello World" application using the ColdFusion on Wheels framework

Chris Peters gives a high level overview of the ORM included with ColdFusion on Wheels

Chris Peters from Liquifusion demonstrates the ColdRoute plugin for Wheels

Doug Boude demonstrates using his new Wirebox plugin for Wheels

Chris Peters from Liquifusion demonstrates creating tables and records using database migrations in ColdFusion on Wheels

Online ColdFusion Meetup (coldfusionmeetup.com) session for March 10 2011, "What's New in Wheels 1.1", with Chris Peters:

A quick demo of the Wheels Textmate bundle by Russ Johnson

Command Line Tools

Core Commands

wheels init

Bootstrap an existing Wheels application for CLI usage.

Synopsis

wheels init

Description

The wheels init command initializes an existing Wheels application to work with the Wheels CLI. It's an interactive command that helps set up necessary configuration files (box.json and server.json) for an existing Wheels installation.

Arguments

This command has no arguments - it runs interactively and prompts for required information.

Options

Option

Description

--help

Show help information

Interactive Prompts

When you run wheels init, you'll be prompted for:

Confirmation - Confirm you want to proceed with initialization
Application Name - Used to make server.json server name unique (if box.json doesn't exist)
CF Engine - Default CFML engine (e.g., lucee5, adobe2021) (if server.json doesn't exist)

Examples

Initialize current directory

wheels init

Example interaction:

==================================== Wheels init ===================================
 This function will attempt to add a few things
 to an EXISTING Wheels installation to help
 the CLI interact.

 We're going to assume the following:
  - you've already setup a local datasource/database
  - you've already set a reload password

 We're going to try and do the following:
  - create a box.json to help keep track of the wheels version
  - create a server.json
====================================================================================

Sound ok? [y/n] y
Please enter an application name: myapp
Please enter a default cfengine: lucee5

What It Does

Creates vendor/wheels/box.json - Tracks the Wheels framework version
Creates server.json - Configures CommandBox server settings with:
- Unique server name based on application name
- Selected CF engine
- Default port and settings
Creates box.json - Main project configuration file with:
- Application name
- Wheels version dependency
- Project metadata

Generated Files

server.json

{
  "name": "myapp",
  "web": {
    "http": {
      "port": 60000
    }
  },
  "app": {
    "cfengine": "lucee5"
  }
}

box.json

{
  "name": "myapp",
  "version": "1.0.0",
  "dependencies": {
    "wheels": "^2.5.0"
  }
}

Prerequisites

Before running wheels init:

Have an existing Wheels application
Database/datasource already configured
Reload password already set in your application settings

Notes

Run this command in the root directory of your Wheels application
Files are only created if they don't already exist
The command detects your current Wheels version automatically
Special characters are stripped from application names

wheels info

Display CLI and Wheels framework version information.

Synopsis

Description

The wheels info command displays information about the Wheels CLI module and identifies the Wheels framework version in the current directory.

Arguments

This command has no arguments.

Options

Option

Description

Output

The command displays:

Wheels ASCII Art - A colorful banner
Current Working Directory - Where you're running the command from
CommandBox Module Root - Where the CLI module is installed
Current Wheels Version - The detected Wheels framework version in this directory

Example Output

Use Cases

Verify CLI installation location
Check Wheels framework version in current directory
Troubleshoot path issues
Quick visual confirmation of Wheels environment

Notes

The Wheels version is detected by looking for box.json files in the vendor/wheels directory
If no Wheels version is found, it will show "Not Found"
The colorful ASCII art helps quickly identify you're using Wheels CLI

wheels reload

Reload the Wheels application in different modes.

Synopsis

Description

The wheels reload command reloads your Wheels application, clearing caches and reinitializing the framework. This is useful during development when you've made changes to configuration, routes, or framework settings. Note: the server must be running for this command to work.

Arguments

Argument

Description

Default

Options

Option

Description

Reload Modes

Development Mode

Enables debugging
Shows detailed error messages
Disables caching
Ideal for active development

Testing Mode

Optimized for running tests
Consistent environment
Predictable caching

Maintenance Mode

Shows maintenance page to users
Allows admin access
Useful for deployments

Production Mode

Full caching enabled
Minimal error information
Optimized performance

Examples

Basic reload (development mode)

Reload in production mode

Using the alias

Reload for testing

Security

The reload password must match the one configured in your Wheels application
Password is sent via URL parameter to the running application
Always use a strong password in production environments

Configuration

Set the reload password in your Wheels settings.cfm:

Notes

Reload clears all application caches
Session data may be lost during reload
Database connections are refreshed
All singletons are recreated
The server must be running for this command to work

Common Issues

Invalid password: Check password in settings.cfm
Server not running: Start server with box server start
Connection refused: Ensure server is accessible on expected port
Timeout: Large applications may take time to reload

Code Generation

Database Commands

Database Operations

wheels db create

Create a new database based on your datasource configuration.

Synopsis

Description

The wheels db create command creates a new database using the connection information from your configured datasource. The datasource must already exist in your CFML server configuration - this command creates the database itself, not the datasource.

Options

--datasource=

Specify which datasource to use. If not provided, uses the default datasource from your Wheels configuration.

--environment=

Specify the environment to use. Defaults to the current environment.

Examples

Basic Usage

Create database using default datasource:

Specific Datasource

Create database for development:

Create database for testing:

Database-Specific Behavior

MySQL/MariaDB

Creates database with UTF8MB4 character set
Uses utf8mb4_unicode_ci collation
Connects to information_schema to execute CREATE DATABASE

PostgreSQL

Creates database with UTF8 encoding
Checks if database already exists before creating
Connects to postgres system database

SQL Server

Creates database with default settings
Checks if database already exists before creating
Connects to master system database

H2

Displays message that H2 databases are created automatically
No action needed - database file is created on first connection

Prerequisites

Datasource Configuration: The datasource must be configured in your CFML server admin
Database Privileges: The database user must have CREATE DATABASE privileges
Network Access: The database server must be accessible

Error Messages

"Datasource not found"

The specified datasource doesn't exist in your server configuration. Create it in your CFML admin first.

"Database already exists"

The database already exists. Use wheels db drop first if you need to recreate it.

"Access denied"

The database user doesn't have permission to create databases. Grant CREATE privileges to the user.

- Drop an existing database
- Create and setup database
- Run migrations after creating database

wheels db drop

Drop an existing database.

Synopsis

Description

The wheels db drop command permanently deletes a database. This is a destructive operation that cannot be undone. By default, it requires confirmation unless the --force flag is used.

Options

--datasource=

Specify which datasource's database to drop. If not provided, uses the default datasource from your Wheels configuration.

--environment=

Specify the environment to use. Defaults to the current environment.

--force

Skip the confirmation prompt. Useful for scripting.

Examples

Basic Usage

Drop database with confirmation:

Force Drop

Drop without confirmation:

Drop Test Database

Safety Features

Confirmation Required: By default, you must type "yes" to confirm
Production Warning: Extra warning when dropping production databases
Clear Messaging: Shows database name and environment before dropping

Database-Specific Behavior

MySQL/MariaDB

Uses DROP DATABASE IF EXISTS statement
Connects to information_schema to execute command

PostgreSQL

Terminates existing connections before dropping
Uses DROP DATABASE IF EXISTS statement
Connects to postgres system database

SQL Server

Sets database to single-user mode to close connections
Uses DROP DATABASE IF EXISTS statement
Connects to master system database

H2

Deletes database files (.mv.db, .lock.db, .trace.db)
Shows which files were deleted

Warning

This operation is irreversible! Always ensure you have backups before dropping a database.

Best Practices

Always backup first:
Use --force carefully: Only in scripts where you're certain
Double-check environment: Especially important for production

Error Messages

"Database not found"

The database doesn't exist. No action needed.

"Access denied"

The database user doesn't have permission to drop databases. Grant DROP privileges to the user.

"Database in use"

Some databases prevent dropping while connections are active. The command attempts to close connections automatically.

- Create a new database
- Drop and recreate database
- Backup before dropping

wheels db setup

Setup a complete database by creating it, running migrations, and seeding data.

Synopsis

Description

The wheels db setup command performs a complete database initialization in one command. It executes three operations in sequence:

Creates the database (wheels db create)
Runs all migrations (wheels dbmigrate latest)
Seeds the database with sample data (wheels db seed)

This is ideal for setting up a new development environment or initializing a test database.

Options

--datasource=

Specify which datasource to use. If not provided, uses the default datasource from your Wheels configuration.

--environment=

Specify the environment to use. Defaults to the current environment.

--skip-seed

Skip the database seeding step.

--seed-count=

Number of records to generate per model when seeding. Defaults to 5.

Examples

Basic Usage

Full setup with default options:

Setup Without Sample Data

Create and migrate only:

Setup Test Database

Production Setup

What It Does

The command executes these steps in order:

Create Database
- Creates new database if it doesn't exist
- Uses datasource configuration for connection details
Run Migrations
- Executes all pending migrations
- Creates schema from migration files
Seed Database (unless --skip-seed)
- Generates sample data for testing
- Creates specified number of records per model

Error Handling

If any step fails:

The command stops execution
Shows which step failed
Provides instructions for manual recovery

Common Use Cases

New Developer Setup

Reset Development Database

Continuous Integration

Best Practices

Use for development: Perfect for getting started quickly
Skip seeding in production: Use --skip-seed for production
Customize seed count: More data for performance testing
Check migrations first: Ensure migrations are up to date

- Just create database
- Drop and recreate everything
- Just run migrations
- Just seed data

wheels db reset

Reset the database by dropping it and recreating it from scratch.

Synopsis

wheels db reset [--datasource=<name>] [--environment=<env>] [--force] [--skip-seed] [--seed-count=<n>]

Description

The wheels db reset command completely rebuilds your database by executing four operations in sequence:

Drops the existing database (wheels db drop)
Creates a new database (wheels db create)
Runs all migrations (wheels dbmigrate latest)
Seeds the database with sample data (wheels db seed)

This is a destructive operation that will delete all existing data.

Options

--datasource=

Specify which datasource to use. If not provided, uses the default datasource from your Wheels configuration.

wheels db reset --datasource=myapp_dev

--environment=

Specify the environment to use. Defaults to the current environment.

wheels db reset --environment=testing

--force

Skip the confirmation prompt. Use with caution!

wheels db reset --force

--skip-seed

Skip the database seeding step.

wheels db reset --skip-seed

--seed-count=

Number of records to generate per model when seeding. Defaults to 5.

wheels db reset --seed-count=20

Examples

Basic Usage

Reset with confirmation:

wheels db reset
# Will prompt: Are you sure you want to reset the database? Type 'yes' to confirm:

Force Reset

Reset without confirmation:

wheels db reset --force

Reset Test Database

wheels db reset --datasource=myapp_test --environment=testing --force

Reset Without Seeding

wheels db reset --skip-seed --force

Safety Features

Confirmation Required: Must type "yes" to confirm (unless --force)
Production Warning: Extra warning for production environment
Special Production Confirmation: Must type "reset production database" for production

Warning

This operation is irreversible! All data will be permanently lost.

Common Use Cases

Development Reset

# When you need a fresh start
wheels db reset --force --seed-count=50

Before Major Changes

# Backup first
wheels db dump --output=backup-before-reset.sql

# Then reset
wheels db reset

Automated Testing

# In test scripts
wheels db reset --environment=testing --force --skip-seed

What Happens

Drop Database
- All tables and data are deleted
- Database is completely removed
Create Database
- Fresh database is created
- Character set and collation are set (MySQL)
Run Migrations
- All migrations run from scratch
- Schema is recreated
Seed Database (unless --skip-seed)
- Sample data is generated
- Useful for development/testing

Error Recovery

If reset fails partway through:

# Manual recovery steps
wheels db drop --force        # Ensure old database is gone
wheels db create             # Create new database
wheels dbmigrate latest      # Run migrations
wheels db seed              # Seed data (optional)

Best Practices

Always backup production data first
Use --force only in automated scripts
Avoid resetting production databases
Use db setup for new databases instead

wheels db setup - Setup new database (non-destructive)
wheels db drop - Just drop database
wheels db dump - Backup before reset
wheels dbmigrate reset - Reset just migrations

wheels db status

Show the status of database migrations.

Synopsis

Description

The wheels db status command displays information about the current state of database migrations, showing which migrations have been applied and which are pending.

Options

--format=

Output format. Options are table (default) or json.

--pending

Show only pending migrations.

Examples

Basic Usage

Show all migrations in table format:

Output:

Show Only Pending

JSON Output

Output:

Understanding the Output

Table Format

Version: Migration timestamp/version number
Description: Human-readable migration name
Status: Either "applied" or "pending"
Applied At: When the migration was run

Status Colors

Green: Applied migrations
Yellow: Pending migrations

Summary Section

Shows counts of:

Total migrations in the migrations folder
Applied migrations in the database
Pending migrations to be run

Common Scenarios

Check Before Deployment

Verify Migration Applied

CI/CD Integration

Troubleshooting

"No migrations found"

Check that migration files exist in /db/migrate/ directory
Ensure file naming follows pattern: YYYYMMDDHHMMSS_Description.cfc

Version Mismatch

If the database version doesn't match expected:

Check migration history in database
Verify no migrations were manually deleted
Consider running wheels dbmigrate latest

- Show just the current version
- Apply pending migrations
- Rollback migrations
- Similar migration information

wheels db version

Show the current database schema version.

Synopsis

Description

The wheels db version command displays the current version of your database schema based on the last applied migration. This is useful for quickly checking which migration version your database is at.

Options

--detailed

Show additional information about the database state.

Examples

Basic Usage

Show current version:

Output:

Detailed Information

Output:

Understanding Versions

Version Format

Migrations use timestamp-based versions:

Format: YYYYMMDDHHMMSS
Example: 20231203160000 = December 3, 2023 at 4:00:00 PM

No Version

If you see "No migrations have been applied yet":

Database is fresh with no migrations run
Run wheels dbmigrate latest to apply migrations

Common Use Cases

Quick Check

Before running migrations:

Deployment Verification

Troubleshooting

Compare versions across environments:

The version corresponds to:

The latest migration file that has been applied
An entry in the migration tracking table
The current schema state of your database

- Show all migrations and their status
- Update to latest version
- Rollback to previous version
- Detailed migration information

Migration Commands

wheels dbmigrate up

Run the next pending database migration.

Synopsis

Alias: wheels db up

Description

The dbmigrate up command executes the next pending migration in your database migration queue. This command is used to incrementally apply database changes one migration at a time, allowing for controlled and reversible database schema updates.

Parameters

None.

Examples

Run the next pending migration

This will execute the next migration in the sequence and update the database schema version.

Use Cases

Incremental Database Updates

When you want to apply database changes one at a time rather than all at once:

Controlled Migration Application

Apply migrations one at a time for better control:

Notes

Migrations are executed in chronological order based on their timestamps
Each migration is tracked in the database to prevent duplicate execution
If already at latest version, displays: "We're all up to date already!"
If no more versions available, displays: "No more versions to go to?"
Automatically runs dbmigrate info after successful migration
Always backup your database before running migrations in production

- Rollback the last migration
- Run all pending migrations
- View migration status
- Reset all migrations

wheels dbmigrate down

Rollback the last executed database migration.

Synopsis

Alias: wheels db down

Description

The dbmigrate down command reverses the last executed migration by running its down() method. This is useful for undoing database changes when issues are discovered or when you need to modify a migration. The command ensures safe rollback of schema changes while maintaining database integrity.

Parameters

None.

Examples

Rollback the last migration

This will execute the down() method of the most recently applied migration, reverting the database changes.

Use Cases

Fixing Migration Errors

When a migration contains errors or needs modification:

Development Iteration

During development when refining migrations:

Emergency Rollback

When a migration causes issues:

Important Considerations

Data Loss Warning

Rolling back migrations that drop columns or tables will result in data loss. Always ensure you have backups before rolling back destructive migrations.

Down Method Requirements

For a migration to be rolled back, it must have a properly implemented down() method that reverses the changes made in the up() method.

Migration Dependencies

Be cautious when rolling back migrations that other migrations depend on. This can break the migration chain.

Best Practices

Always implement down() methods: Even if you think you'll never need to rollback
Test rollbacks: In development, always test that your down() method works correctly
Backup before rollback: Especially in production environments
Document destructive operations: Clearly indicate when rollbacks will cause data loss

Notes

Only the last executed migration can be rolled back with this command
To rollback multiple migrations, run the command multiple times
If already at version 0, displays: "We're already on zero! No migrations to go to"
Automatically runs dbmigrate info after successful rollback
The migration version is removed from the database tracking table upon successful rollback
Some operations (like dropping columns with data) cannot be fully reversed
When migrating to version 0, displays: "Database should now be empty."

- Run the next migration
- Reset all migrations
- View migration status
- Run a specific migration

wheels dbmigrate exec

Execute a specific database migration by version number.

Synopsis

Alias: wheels db exec

Description

The dbmigrate exec command allows you to migrate to a specific version identified by its version number, regardless of the current migration state. This is useful for moving to any specific point in your migration history.

Parameters

Parameter

Type

Required

Description

Examples

Execute a specific migration

Migrate to version 0 (revert all migrations)

Use Cases

Migrating to a Specific Version

Move to any point in migration history:

Rolling Back to Previous Version

Move to an earlier migration state:

Reset Database

Clear all migrations:

Important Considerations

Migration Order

Executing migrations out of order can cause issues if migrations have dependencies. Always ensure that any required preceding migrations have been run.

Version Tracking

The command updates the migration tracking table to reflect the execution status.

Best Practices

Check Dependencies: Ensure required migrations are already applied
Test First: Run in development/testing before production
Use Sparingly: Prefer normal migration flow with up/latest
Document Usage: Record when and why specific executions were done
Verify State: Check migration status before and after execution

Version Number Format

Migration versions are typically timestamps in the format:

YYYYMMDDHHmmss (e.g., 20240115123456)
Year: 2024
Month: 01
Day: 15
Hour: 12
Minute: 34
Second: 56

Notes

The command will migrate UP or DOWN to reach the specified version
Version must be a valid migration version or 0 to reset all
The migration file must exist in the migrations directory
The command displays the migration progress message
Both up() and down() methods should be defined in the migration

- Run the next migration
- Rollback last migration
- Run all pending migrations
- View migration status
- Create a new migration

Testing Commands

wheels config list

List all configuration settings for your Wheels application.

Usage

Parameters

--environment - (Optional) Environment to display settings for: development, testing, production
--filter - (Optional) Filter results by this string
--show-sensitive - (Optional) Show sensitive information (passwords, keys, etc.)

Description

The wheels config list command displays all configuration settings for your Wheels application. It shows current values and helps you understand your application's configuration state.

Examples

List all settings

Filter by pattern

Show sensitive values

Environment-specific settings

Combined options

Output Example

When using --show-sensitive, password values are displayed:

Common Configuration Settings

The command displays all Wheels configuration settings including:

Database: dataSourceName, dataSourceUserName, dataSourcePassword
Cache: cacheQueries, cacheActions, cachePages, cachePartials
Security: reloadPassword, showDebugInformation, showErrorInformation
URLs/Routing: urlRewriting, assetQueryString, assetPaths
Environment: environment, hostName

Filtering

Use the --filter parameter to search for specific settings:

Security

By default, sensitive values like passwords are masked with asterisks (********). Use --show-sensitive to display actual values:

Environment-Specific Settings

View settings for different environments:

Notes

Some settings require restart to take effect
Sensitive values are automatically hidden
Custom settings from plugins included
Performance impact minimal

wheels config set

Set configuration values for your Wheels application.

Usage

Parameters

setting - (Required) Key=Value pair for the setting to update
--environment - (Optional) Environment to apply settings to: development, testing, production, all. Default: development
--encrypt - (Optional) Encrypt sensitive values

Description

The wheels config set command updates configuration settings in your Wheels application. Settings must be provided in key=value format.

Examples

Set basic configuration

Set for specific environment

Set for all environments

Set encrypted value

Configuration Values

The command accepts various value types:

String Values

Boolean Values

Numeric Values

Where Settings Are Saved

Settings are saved to environment-specific configuration files:

Development: /config/development/settings.cfm
Testing: /config/testing/settings.cfm
Production: /config/production/settings.cfm
All environments: /config/settings.cfm

Example:

Sensitive Values

Use the --encrypt flag for sensitive values:

Environment-Specific Settings

Target specific environments with the --environment flag:

Best Practices

Use environment-specific settings: Don't set production values in development
Encrypt sensitive data: Use --encrypt for passwords and keys
Test changes: Verify settings with wheels config list
Restart after changes: Some settings require application restart

Notes

Some settings require application restart
Encrypted values can't be read back
Changes are logged for audit
Use environment variables for containers

wheels config env

Manage environment-specific configuration for your Wheels application.

Usage

wheels config env <action> [source] [target]

Parameters

action - (Required) Action to perform: list, create, copy
source - (Optional) Source environment for copy action
target - (Optional) Target environment for create or copy action

Description

The wheels config env command provides tools for managing environment-specific configurations. It helps you list, create, and copy configurations between different environments.

Examples

List all environments

wheels config env list

Create a new environment

wheels config env create production

Copy environment configuration

wheels config env copy development production

Actions

List Environments

Display all available environments:

wheels config env list

Output:

Available Environments:
----------------------
• development (active)
• testing
• maintenance  
• production

Create Environment

Create a new environment configuration:

wheels config env create staging

This creates a new environment configuration file at /config/staging/settings.cfm.

Copy Environment

Copy configuration from one environment to another:

wheels config env copy development staging

This copies all settings from the development environment to the staging environment, preserving environment-specific values like datasource names.

Notes

Some operations require application restart
Sensitive values protected by default
Changes logged for audit purposes
Use templates for consistency

Environment Management

Server Management

wheels server

Manage the Wheels development server with enhanced functionality.

Synopsis

wheels server [subcommand] [options]

Description

The wheels server command provides a suite of server management tools that wrap CommandBox's native server functionality with Wheels-specific enhancements. These commands add validation, helpful error messages, and integration with the Wheels framework.

Available Subcommands

start - Start the development server
stop - Stop the development server
restart - Restart the development server
status - Show server status
log - Tail server logs
open - Open application in browser

Key Features

Wheels Application Validation

All server commands check that you're working in a valid Wheels application directory before executing. This prevents common errors and provides helpful guidance.

Enhanced Status Information

When checking server status, the commands also display:

Wheels framework version
Application root directory
Quick action suggestions

Integrated Restart

The restart command not only restarts the server but also reloads the Wheels application, ensuring your changes are picked up.

Smart Browser Opening

The open command can open specific paths in your application and works with your preferred browser.

Examples

# Display available server commands
wheels server

# Start server on port 8080
wheels server start port=8080

# Check if server is running
wheels server status

# Tail the server logs
wheels server log

# Open admin panel in browser
wheels server open /admin

Configuration

Server settings can be configured through:

Command line options - Pass options directly to commands
server.json - Create a server.json file in your project root
box.json - Configure server settings in your box.json

Example server.json:

{
  "web": {
    "port": 8080,
    "host": "127.0.0.1",
    "rewrites": {
      "enable": true
    }
  }
}

Integration with CommandBox

These commands are thin wrappers around CommandBox's native server commands, providing:

Validation specific to Wheels applications
Better error messages and guidance
Integration with Wheels-specific features
Consistent command structure

You can always use the native CommandBox commands directly if needed:

# Native CommandBox commands still work
server start
server stop
server status

Troubleshooting

Server won't start

Check if a server is already running: wheels server status
Try forcing a start: wheels server start --force
Check for port conflicts: wheels server start port=8081

Can't find Wheels application

Ensure you're in a directory containing:

/vendor/wheels - The Wheels framework
/config - Configuration files
/app - Application code

Server starts but application doesn't work

Check logs: wheels server log
Verify database connection in datasource settings
Try reloading: wheels reload

wheels server start

Start the Wheels development server with enhanced checks and features.

Synopsis

Description

The wheels server start command starts a CommandBox server with Wheels-specific enhancements. It checks that you're in a valid Wheels application directory before starting and provides helpful error messages if not.

This command wraps CommandBox's native server start functionality while adding:

Validation that the current directory is a Wheels application
Automatic detection of existing running servers
Wheels-specific configuration suggestions
Integration with Wheels application context

Options

`port`

Type: Numeric
Description: Port number to start server on
Example: wheels server start port=8080

`host`

Type: String
Default: 127.0.0.1
Description: Host/IP address to bind server to
Example: wheels server start host=0.0.0.0

`--rewritesEnable`

Type: Boolean flag
Description: Enable URL rewriting for clean URLs
Example: wheels server start --rewritesEnable

`openbrowser`

Type: Boolean
Default: true
Description: Open browser after starting server
Example: wheels server start openbrowser=false

`directory`

Type: String
Default: Current working directory
Description: Directory to serve
Example: wheels server start directory=/path/to/app

`name`

Type: String
Description: Name for the server instance
Example: wheels server start name=myapp

`--force`

Type: Boolean flag
Description: Force start even if server is already running
Example: wheels server start --force

Examples

Basic Usage

Advanced Usage

Notes

The command validates that the current directory contains a Wheels application by checking for /vendor/wheels, /config, and /app directories
If a server is already running, use --force to start anyway or wheels server restart to restart
After starting, the command displays helpful information about other server commands
The server configuration can also be managed through server.json file

- Stop the server
- Restart the server
- Check server status
- View server logs
- Open in browser

wheels server restart

Restart the Wheels development server and reload the application.

Synopsis

Description

The wheels server restart command restarts a running CommandBox server and automatically reloads the Wheels application. This ensures that both server-level and application-level changes are picked up.

Options

`name`

Type: String
Description: Name of the server to restart
Example: wheels server restart name=myapp

`--force`

Type: Boolean flag
Description: Force restart even if server appears stopped
Example: wheels server restart --force

Examples

What It Does

Stops the running server
Starts the server again with the same configuration
Automatically runs wheels reload to refresh the application
Confirms successful restart

Notes

This command is particularly useful when you've made changes to server configuration or installed new dependencies
The automatic application reload ensures that Wheels picks up any code changes
If the reload fails, you may need to manually refresh your browser

- Start the server
- Stop the server
- Check server status
- Reload just the application

wheels server log

Tail the Wheels development server logs.

Synopsis

Description

The wheels server log command displays and follows the server log output, making it easy to monitor your application's behavior and debug issues.

Options

`name`

Type: String
Description: Name of the server whose logs to display
Example: wheels server log name=myapp

`--follow`

Type: Boolean flag
Default: true
Description: Follow log output (like tail -f)
Example: wheels server log --follow

`lines`

Type: Numeric
Default: 50
Description: Number of lines to show initially
Example: wheels server log lines=100

`--debug`

Type: Boolean flag
Description: Show debug-level logging
Example: wheels server log --debug

Examples

Log Information

The logs typically include:

HTTP request/response information
Application errors and stack traces
Database queries (if enabled)
Custom application logging
Server startup/shutdown messages

Keyboard Shortcuts

Ctrl+C - Stop following logs and return to command prompt
Ctrl+L - Clear the screen (while following)

Notes

By default, the command follows log output (similar to tail -f)
Use --debug to see more detailed logging information
The number of initial lines shown can be customized with the lines parameter
Logs are stored in the CommandBox server's log directory

- Start the server
- Check server status
- Debug mode for tests

Plugin Management

wheels plugins list

Lists installed Wheels CLI plugins or shows available plugins from ForgeBox.

Usage

wheels plugins list [--global] [--format=<format>] [--available]

Parameters

--global - (Optional) Show globally installed plugins
--format - (Optional) Output format: table, json. Default: table
--available - (Optional) Show available plugins from ForgeBox

Description

The plugins list command displays information about all plugins installed in your Wheels application, including:

Plugin name and version
Installation status (active/inactive)
Compatibility with current Wheels version
Description and author information
Dependencies on other plugins

Examples

List all local plugins

wheels plugins list

Show globally installed plugins

wheels plugins list --global

Export as JSON

wheels plugins list --format=json

Show available plugins from ForgeBox

wheels plugins list --available

Output

Table Format (Default)

🧩 Installed Wheels CLI Plugins

Name                Version    Description
---------------------------------------------
wheels-vue-cli      1.2.0     Vue.js integration for Wheels
wheels-docker       2.0.1     Docker deployment tools
wheels-testing      1.5.0     Advanced testing utilities

Total: 3 plugins

Available Plugins from ForgeBox

================ Available Wheels Plugins From ForgeBox ======================
[Lists all available cfwheels-plugins from ForgeBox]
=============================================================================

JSON Format

{
  "plugins": [
    {
      "name": "wheels-vue-cli",
      "version": "1.2.0",
      "description": "Vue.js integration for Wheels"
    }
  ]
}

Notes

Local plugins are stored in your project
Global plugins are available to all projects
Use wheels plugins install to add new plugins
Use wheels plugins remove to uninstall plugins
The --available flag queries the ForgeBox registry

wheels plugins install

Installs a Wheels CLI plugin from various sources including ForgeBox, GitHub, or local files.

Usage

Parameters

name - (Required) Plugin name or repository URL
--dev - (Optional) Install as development dependency
--global - (Optional) Install globally
--version - (Optional) Specific version to install

Description

The plugins install command downloads and installs Wheels plugins into your application. It supports multiple installation sources:

ForgeBox Registry: Official and community plugins
GitHub Repositories: Direct installation from GitHub
Local Files: ZIP files or directories
URL Downloads: Direct ZIP file URLs

The command automatically:

Checks plugin compatibility
Resolves dependencies
Backs up existing plugins
Runs installation scripts

Examples

Install from ForgeBox

Install specific version

Install from GitHub

Install as development dependency

Install globally

Install with multiple options

Installation Process

Download: Fetches plugin from specified source
Validation: Checks compatibility and requirements
Backup: Creates backup of existing plugin (if any)
Installation: Extracts files to plugins directory
Dependencies: Installs required dependencies
Initialization: Runs plugin setup scripts
Verification: Confirms successful installation

Output

If installation fails:

Plugin Sources

ForgeBox

GitHub

Direct URL

Notes

Plugins must be compatible with your Wheels version
Always backup your application before installing plugins
Some plugins require manual configuration after installation
Use wheels plugins list to verify installation
Restart your application to activate new plugins

wheels plugins remove

Removes an installed Wheels CLI plugin.

Usage

wheels plugins remove <name> [--global] [--force]

Parameters

name - (Required) Plugin name to remove
--global - (Optional) Remove globally installed plugin
--force - (Optional) Force removal without confirmation

Description

The plugins remove command safely uninstalls a plugin from your Wheels application. It:

Checks for dependent plugins
Creates a backup (by default)
Removes plugin files
Cleans up configuration
Updates plugin registry

Examples

Basic plugin removal

wheels plugins remove wheels-vue-cli

Remove global plugin

wheels plugins remove wheels-docker --global

Force removal (skip confirmation)

wheels plugins remove wheels-testing --force

Remove global plugin without confirmation

wheels plugins remove wheels-cli-tools --global --force

Removal Process

Dependency Check: Ensures no other plugins depend on this one
Backup Creation: Saves plugin files to backup directory
Deactivation: Disables plugin in application
File Removal: Deletes plugin files and directories
Cleanup: Removes configuration entries
Verification: Confirms successful removal

Output

With confirmation prompt (default)

Are you sure you want to remove the plugin 'wheels-vue-cli'? (y/n): y
🗑️  Removing plugin: wheels-vue-cli...

✅ Plugin removed successfully

With force flag

🗑️  Removing plugin: wheels-vue-cli...

✅ Plugin removed successfully

Cancellation

Are you sure you want to remove the plugin 'wheels-vue-cli'? (y/n): n
Plugin removal cancelled.

Notes

The --force flag skips the confirmation prompt
Use --global to remove plugins installed globally
Use wheels plugins list to verify removal
Some plugins may require manual cleanup of configuration files
Restart your application after removing plugins that affect core functionality

Code Analysis

wheels analyze code

Analyzes code quality in your Wheels application, checking for best practices, potential issues, and code standards compliance.

Usage

Parameters

path - (Optional) Path to analyze. Default: current directory (.)
--fix - (Optional) Attempt to fix issues automatically
--format - (Optional) Output format: console, json, junit. Default: console
--severity - (Optional) Minimum severity level: info, warning, error. Default: warning
--report - (Optional) Generate HTML report

Description

The analyze code command performs comprehensive code quality analysis on your Wheels application. It checks for:

Code complexity and maintainability
Adherence to Wheels coding standards
Potential bugs and code smells
Duplicate code detection
Function length and complexity metrics
Variable naming conventions
Deprecated function usage

Examples

Basic code analysis

Analyze specific directory

Auto-fix issues

Generate HTML report

Analyze with JSON output for CI/CD

Check only errors (skip warnings)

Analyze and fix specific path with report

Output

The command provides detailed feedback including:

Complexity Score: Cyclomatic complexity for functions
Code Standards: Violations of Wheels conventions
Duplicate Code: Similar code blocks that could be refactored
Suggestions: Recommendations for improvement
Metrics Summary: Overall code health indicators

Notes

Large codebases may take several minutes to analyze
The --fix flag will automatically fix issues where possible
HTML reports are saved to the reports/ directory with timestamps
Integration with CI/CD pipelines is supported via JSON and JUnit output formats
Use .wheelscheck config file for custom rules and configurations

wheels analyze performance

Analyzes application performance, identifying bottlenecks and optimization opportunities in your Wheels application.

Usage

Parameters

--target - (Optional) Analysis target: all, controller, view, query, memory. Default: all
--duration - (Optional) Duration to run analysis in seconds. Default: 30
--report - (Optional) Generate HTML performance report
--threshold - (Optional) Performance threshold in milliseconds. Default: 100
--profile - (Optional) Enable profiling mode

Description

The analyze performance command profiles your Wheels application to identify performance bottlenecks and provide optimization recommendations. It monitors:

Request execution times
Database query performance
Memory usage patterns
Cache effectiveness
View rendering times
Component instantiation overhead

Examples

Basic performance analysis

Analyze for 60 seconds with profiling

Focus on database queries only

Show only slow operations (>500ms)

Generate HTML performance report

Complete analysis with all options

Output

The analysis provides:

Slowest Requests: Top 10 slowest request paths
Query Analysis: Slow queries and N+1 query detection
Memory Hotspots: Areas of high memory allocation
Cache Statistics: Hit/miss ratios for various caches
Recommendations: Specific optimization suggestions

Sample Output

Notes

Profiling adds minimal overhead to your application
Best run in a staging environment with production-like data
Can be integrated with APM tools for continuous monitoring
Results are aggregated across all application instances

Security Commands

Upgrading

Instructions for upgrading Wheels applications

Wheels follows Semantic Versioning (http://semver.org/) so large version changes (e.g, 1.x.x -> 2.x.x) will most likely contain breaking changes which will require evaluation of your codebase. Minor version changes (e.g, 1.3.x->1.4.x) will often contain new functionality, but in a backwards-compatible manner, and maintenance releases (e.g 1.4.4 -> 1.4.5) will just be trying to fix bugs.

Generally speaking, upgrading Wheels is as easy as replacing the wheels folder, especially for those small maintenance releases: however, there are usually exceptions in minor point releases (i.e, 1.1 to 1.3 required replacing other files outside the wheels folder). The notes below detail those changes.

Upgrading to 3.0.0

Compatibility Changes

Adobe Coldfusion 2016 and below are no longer compatible with Wheels going forward. Consequently, these versions have been removed from the Wheels Internal Test Suites.

Code changes

Migrate your tests from the tests directory which are written with rocketUnit and rewrite them into Testbox in the tests/Testbox directory. Starting with Wheels 3.x, Testbox will replace RocketUnit as the default testing framework.
Starting with Wheels 3.x, Wirebox will be used as the default dependency injector.
After installing Wheels 3.x, you'll have to run box install to intall testbox and wirebox in your application as they are not shipped with Wheels but are rather listed in box.json file as dependencies to be installed.
Added Mappings for the app, vendor, wheels, wirebox, testbox and tests directories.
root.cfm and rewrite.cfm have been removed. All the requests are now being redirected only through public/index.cfm.
A .env file has been added in the root of the application which adds the H2 database extension for lucee and sets the cfadmin password to commandbox for both Lucee and Adobe ColdFusion.

Changes to the wheels folder

Replace the wheels folder with the new one from the 3.0.0 download.
Move the wheels folder inside the vendor folder.

Changes outside the wheels folder

Moved the config, controllers, events, global, lib, migrator, models, plugins, snippets and views directories inside the app directory.
Moved the files, images, javascripts, miscellaneous, stylesheets directories and Application.cfc, index.cfm and urlrewrite.xml files into the public folder.

Upgrading to 2.3.x

Replace the wheels folder with the new one from the 2.3.0 download.

Upgrading to 2.2.x

Replace the wheels folder with the new one from the 2.2.0 download.

Upgrading to 2.1.x

Replace the wheels folder with the new one from the 2.1.0 download.

Code changes

Rename any instances of findLast() to findLastOne()

Changes outside the wheels folder

Create /events/onabort.cfm to support the onAbort method

Upgrading to 2.0.x

As always, the first step is to replace the wheels folder with the new one from the 2.0 download.

Other major changes required to upgrade your application are listed in the following sections.

Supported CFML Engines

Wheels 2.0 requires one of these CFML engines:

Lucee 4.5.5.006 + / 5.2.1.9+
Adobe ColdFusion 10.0.23 / 11.0.12+ / 2016.0.4+

We've updated our minimum requirements to match officially supported versions from the vendors. (For example, Adobe discontinued support for ColdFusion 10 in May 2017, which causes it to be exposed to security exploits in the future. We've included it in 2.0 but it may be discontinued in a future version)

Changes outside the wheels folder

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 must be renamed to config.
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.
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 behavior).
The renderPage function has been renamed to renderView
includePartial() now requires the partial and query arguments to be set (if using a query)

Routing

The addRoute() function has been removed in Wheels 2.0 in favor of a new routing API. See the Routing chapter for information about the new RESTful routing system.

A limited version of the "wildcard" route ([controller]/[action]/[key]) is available as [controller]/[action]) if you use the new wildcard() mapper method:

/config/routes.cfm

mapper()
    .wildcard()
.end();

By default, this is limited to GET requests for security reasons.

Cross-Site Request Forgery (CSRF) Protection

It is strongly recommended that you enable Wheels 2.0's built-in CSRF protection.

For many applications, you need to follow these steps:

In controllers/Controller.cfc, add a call to protectsFromForgery() to the config method.
Add a call to the csrfMetaTags() helper in your layouts' <head> sections.
Configure any AJAX calls that POST data to your application to pass the authenticityToken from the <meta>tags generated by csrfMetaTags() as an X-CSRF-TOKEN HTTP header.
Update your route definitions to enforce HTTP verbs on actions that manipulate data (get, post, patch, delete, etc.)
Make sure that forms within the application are POSTing data to the actions that require post, patch, and delete verbs.

See documentation for the CSRF Protection Plugin for more information.

Note: If you had previously installed the CSRF Protection plugin, you may remove it and rely on the functionality included in the Wheels 2 core.

Database Migrations

If you have previously been using the dbmigrate plugin, you can now use the inbuilt version within the Wheels 2 core.

Database Migration files in /db/migrate/ should now be moved to /app/migrator/migrations/ and extend wheels.migrator.Migration, not plugins.dbmigrate.Migration which can be changed with a simple find and replace. Note: Oracle is not currently supported for Migrator.

Upgrading to 1.4.x

Replace the wheels folder with the new one from the 1.4 download.
Replace URL rewriting rule files – i.e, .htaccess, web.config, IsapiRewrite.ini

In addition, if you're upgrading from an earlier version of Wheels, we recommend reviewing the instructions from earlier reference guides below.

Upgrading to 1.3.x

If you are upgrading from Wheels 1.1.0 or newer, follow these steps:

Replace the wheels folder with the new one from the 1.3 download.
Replace the root root.cfm file with the new one from the 1.3 download.
Remove the <cfheader> calls from the following files:
- events/onerror.cfm
- events/onmaintenance.cfm
- events/onmissingtemplate.cfm

In addition, if you're upgrading from an earlier version of Wheels, we recommend reviewing the instructions from earlier reference guides below.

Note: To accompany the newest 1.1.x releases, we've highlighted the changes that are affected by each release in this cycle.

Upgrading to 1.1.x

If you are upgrading from Wheels 1.0 or newer, the easiest way to upgrade is to replace the wheels folder with the new one from the 1.1 download. If you are upgrading from an earlier version, we recommend reviewing the steps outlined in Upgrading to Wheels 1.0.

Note: To accompany the newest 1.1.x releases, we've highlighted the changes that are affected by each release in this cycle.

Plugin Compatibility

Be sure to review your plugins and their compatibility with your newly-updated version of Wheels. Some plugins may stop working, throw errors, or cause unexpected behavior in your application.

Supported System Changes

1.1: The minimum Adobe ColdFusion version required is now 8.0.1.
1.1: The minimum Railo version required is now 3.1.2.020.
1.1: The H2 database engine is now supported.

File System Changes

1.1: The .htaccess file has been changed. Be sure to copy over the new one from the new version 1.1 download and copy any addition changes that you may have also made to the original version.

Database Structure Changes

1.1: By default, Wheels 1.1 will wrap database queries in transactions. This requires that your database engine supports transactions. For MySQL in particular, you can convert your MyISAM tables to InnoDB to be compatible with this new functionality. Otherwise, to turn off automatic transactions, place a call to set(transactionMode="none").
1.1: Binary data types are now supported.

CFML Code Changes

Model Code

1.1: Validations will be applied to some model properties automatically. This may cause unintended behavior with your validations. To turn this setting off, call set(automaticValidations=false) in config/settings.cfm.
1.1: The class argument in hasOne(), hasMany(), and belongsTo() has been deprecated. Use the modelName argument instead.
1.1: afterFind() callbacks no longer require special logic to handle the setting of properties in objects and queries. (The "query way" works for both cases now.) Because arguments will always be passed in to the method, you can't rely on StructIsEmpty() to determine if you're dealing with an object or not. In the rare cases that you need to know, you can now call isInstance() or isClass() instead.
1.1: On create, a model will now set the updatedAt auto-timestamp to the same value as the createdAt timestamp. To override this behavior, call set(setUpdatedAtOnCreate=false) in config/settings.cfm.

View Code

1.1: Object form helpers (e.g. textField() and radioButton()) now automatically display a label based on the property name. If you left the label argument blank while using an earlier version of Wheels, some labels may start appearing automatically, leaving you with unintended results. To stop a label from appearing, use label=false instead.
1.1: The contentForLayout() helper to be used in your layout files has been deprecated. Use the includeContent() helper instead.
1.1: In production mode, query strings will automatically be added to the end of all asset URLs (which includes JavaScript includes, stylesheet links, and images). To turn off this setting, call set(assetQueryString=false) in config/settings.cfm.
1.1: stylesheetLinkTag() and javaScriptIncludeTag() now accept external URLs for the source/sources argument. If you manually typed out these tags in previous releases, you can now use these helpers instead.
1.1: flashMessages(), errorMessageOn(), and errorMessagesFor() now create camelCased class attributes instead (for example error-messages is now errorMessages). The same goes for the class attribute on the tag that wraps form elements with errors: it is now fieldWithErrors.

Controller Code

1.1.1: The if argument in all validation functions is now deprecated. Use the condition argument instead.

Upgrading to 1.0.x

Our listing of steps to take while upgrading your Wheels application from earlier versions to 1.0.x.

Upgrading from an earlier version of 1.x? Then the upgrade path is simple. All you need to do is replace the wheels folder with the new wheels folder from the download.

The easiest way to upgrade is to setup an empty website, deploy a fresh copy of Wheels 1.0, and then transfer your application code to it. When transferring, please make note of the following changes and make the appropriate changes to your code.

Note: To accompany the newest 1.0 release, we've highlighted the changes that are affected by that release.

Supported System Changes

1.0: URL rewriting with IIS 7 is now supported.
1.0: URL rewriting in a sub folder on Apache is now supported.
ColdFusion 9 is now supported.
Oracle 10g or later is now supported.
PostgreSQL is now supported.
Railo 3.1 is now supported.

File System Changes

1.0: There is now an app.cfm file in the config folder. Use it to set variables that you'd normally set in Application.cfc (i.e., this.name, this.sessionManagement, this.customTagPaths, etc.)
1.0: There is now a web.config file in the root.
1.0: There is now a Wheels.cfc file in the models folder.
1.0: The Wheels.cfc file in the controllers folder has been updated.
1.0: The IsapiRewrite4.ini and .htaccess files in the root have both been updated.
The controller folder has been changed to controllers.
The model folder has been changed to models.
The view folder has been changed to views.
Rename all of your CFCs in models and controllers to UpperCamelCase. So controller.cfc will become Controller.cfc, adminUser.cfc will become AdminUser.cfc, and so on.
All images must now be stored in the images folder, files in the files folder, JavaScript files in the javascripts folder, and CSS files in the stylesheets folder off of the root.

Database Structure Changes

deletedOn, updatedOn, and createdOn are no longer available as auto-generated fields. Please change the names to deletedAt, updatedAt, and createdAt instead to get similar functionality, and make sure that they are of type datetime, timestamp, or equivalent.

CFML Code Changes

Config Code

1.0: The action of the default route (home) has changed to wheels. The way configuration settings are done has changed quite a bit. To change a Wheels application setting, use the new set() function with the name of the Wheels property to change. (For example, <cfset set(dataSourceName="mydatasource")>.) To see a list of available Wheels settings, refer to the Configuration and Defaults chapter. Model Code
1.0: The extends attribute in models/Model.cfc should now be Wheels.
findById() is now called findByKey(). Additionally, its id argument is now named key instead. For composite keys, this argument will accept a comma-delimited list.
When using a model's findByKey() or findOne() functions, the found property is no longer available. Instead, the functions return false if the record was not found.
A model's errorsOn() function now always returns an array, even if there are no errors on the field. When there are errors for the field, the array elements will contain a struct with name, fieldName, and message elements.
The way callbacks are created has changed. There is now a method for each callback event ( beforeValidation(), beforeValidationOnCreate(), etc.) that should be called from your model's init() method. These methods take a single argument: the method within your model that should be invoked during the callback event. See the chapter on Object Callbacks for an example.

View Code

1.0: The contents of the views/wheels folder have been changed.
The wrapLabel argument in form helpers is now replaced with labelPlacement. Valid values for labelPlacement are before, after, and around.
The first argument for includePartial() has changed from name to partial. If you're referring to it through a named argument, you'll need to replace all instances with partial.
The variable that keeps a counter of the current record when using includePartial() with a query has been renamed from currentRow to current.
There is now an included wheels view folder in views. Be sure to copy that into your existing Wheels application if you're upgrading.
The location of the default layout has changed. It is now stored at /views/layout.cfm. Now controller-specific layouts are stored in their respective view folder as layout.cfm. For example, a custom layout for www.domain.com/about would be stored at /views/about/layout.cfm.
In linkTo(), the id argument is now called key. It now accepts a comma-delimited list in the case of composite keys.
The linkTo() function also accepts an object for the key argument, in which case it will automatically extract the keys from it for use in the hyperlink.
The linkTo() function can be used only for controller-, action-, and route-driven links now. * The url argument has been removed, so now all static links should be coded using a standard "a" tag.

Controller Code

1.0: The extends attribute in controllers/Controller.cfc should now be Wheels. Multiple-word controllers and actions are now word-delimited by hyphens in the URL. For example, if your controller is called SiteAdmin and the action is called editLayout, the URL to access that action would be http://www.domain.com/site-admin/edit-layout.

URL/Routing

The default route for Wheels has changed from [controller]/[action]/[id] to [controller]/[action]/[key]. This is to support composite keys. The params.id value will now only be available as params.key.
You can now pass along composite keys in the URL. Delimit multiple keys with a comma. (If you want to use this feature, then you can't have a comma in the key value itself).

Beginner Tutorial: Hello Database

A quick tutorial that demonstrates how quickly you can get database connectivity up and running with Wheels.

Wheels's built in model provides your application with some simple and powerful functionality for interacting with databases. To get started, you will make some simple configurations, call some functions within your controllers, and that's it. Best yet, you will rarely ever need to write SQL code to get those redundant CRUD tasks out of the way.

Our Sample Application: User Management

We'll learn by building part of a sample user management application. This tutorial will teach you the basics of setting up a resource that interacts with the Wheels ORM.

Download source code

You can download all the source code for this sample application from https://github.com/dhgassoc/Wheels-Beginner-Tutorial-Hello-Database

Setting up the Data Source

By default, Wheels will connect to a data source wheels.dev. To change this default behavior, open the file at /config/settings.cfm. In a fresh install of Wheels, you'll see the follwing code:

/config/settings.cfm

<cfscript>
	/*
		Use this file to configure your application.
		You can also use the environment specific files (e.g. /config/production/settings.cfm) to override settings set here.
		Don't forget to issue a reload request (e.g. reload=true) after making changes.
		See https://guides.wheels.dev/2.5.0/v/3.0.0-snapshot/working-with-wheels/configuration-and-defaults for more info.
	*/

	/*
		You can change the "wheels.dev" value from the two functions below to set your datasource.
		You can change the the value for the "dataSourceName" to set a default datasource to be used throughout your application.
		You can also change the value for the "coreTestDataSourceName" to set your testing datasource.
	*/
	set(coreTestDataSourceName="wheels.dev");
	set(dataSourceName="wheels.dev");
    // set(dataSourceUserName="");
    // set(dataSourcePassword="");

	/*
		If you comment out the following line, Wheels will try to determine the URL rewrite capabilities automatically.
		The "URLRewriting" setting can bet set to "on", "partial" or "off".
		To run with "partial" rewriting, the "cgi.path_info" variable needs to be supported by the web server.
		To run with rewriting set to "on", you need to apply the necessary rewrite rules on the web server first.
	*/
	set(URLRewriting="On");

	// Reload your application with ?reload=true&password=wheels.dev
	set(reloadPassword="wheels.dev");

	// CLI-Appends-Here
</cfscript>

These lines provide Wheels with the necessary information about the data source, URL rewriting, and reload password for your application, and include the appropriate values. This may include values for dataSourceName, dataSourceUserName, and dataSourcePassword. More on URL rewriting and reload password later.

/config/settings.cfm

set(dataSourceName="back2thefuture");
// set(dataSourceUserName="marty");
// set(dataSourcePassword="mcfly");

Our Sample Data Structure

Wheels supports MySQL, SQL Server, PostgreSQL, and H2. It doesn't matter which DBMS you use for this tutorial; we will all be writing the same CFML code to interact with the database. Wheels does everything behind the scenes that needs to be done to work with each DBMS.

That said, here's a quick look at a table that you'll need in your database, named users:

Column Name

Data Type

Extra

int

auto increment

username

varchar(100)

varchar(255)

passwd

varchar(15)

Note a couple things about this users table:

The table name is plural.
The table has an auto-incrementing primary key named id.

These are database conventions used by Wheels. This framework strongly encourages that everyone follow convention over configuration. That way everyone is doing things mostly the same way, leading to less maintenance and training headaches down the road.

Fortunately, there are ways of going outside of these conventions when you really need it. But let's learn the conventional way first. Sometimes you need to learn the rules before you can know how to break them.

Creating Routes for the users Resource

Next, open the file at /config/routes.cfm. You will see contents similar to this:

/config/routes.cfm

mapper()
    .wildcard()
    .root(method = "get")
.end();

We are going to create a section of our application for listing, creating, updating, and deleting user records. In Wheels routing, this requires a plural resource, which we'll name users.

Because a users resource is more specific than the "generic" routes provided by Wheels, we'll list it first in the chain of mapper method calls:

/config/routes.cfm

mapper()
    .resources("users")
    .wildcard()
    .root(method = "get")
.end();

This will create URL endpoints for creating, reading, updating, and deleting user records:

Name

Method

URL Path

Description

users

GET

/users

Lists users

newUsers

GET

/users/new

Display a form for creating a user record

users

POST

/users

Form posts a new user record to be created

editUser

GET

/users/[id]/edit

Displays a form for editing a user record

user

PATCH

/users/[id]

Form posts an existing user record to be updated

user

DELETE

/users/[id]

Deletes a user record

Name is referenced in your code to tell Wheels where to point forms and links.
Method is the HTTP verb that Wheels listens for to match up the request.
URL Path is the URL that Wheels listens for to match up the request.

Don't forget to reload

You will need to reload your application after adding new routes!

Creating Users

First, let's create a simple form for adding a new user to the users table. To do this, we will use Wheels's form helper functions. Wheels includes a whole range of functions that simplifies all of the tasks that you need to display forms and communicate errors to the user.

Creating the Form

Now create a new file in app/views/users called new.cfm. This will contain the view code for our simple form.

Next, add these lines of code to the new file:

app/views/users/new.cfm

<cfoutput>

<h1>New User</h1>

#startFormTag(route="users")#
    <div>
        #textField(objectName="user", property="username", label="Username")#
    </div>

    <div>
        #textField(objectName="user", property="email", label="Email")#
    </div>

    <div>
        #passwordField(
            objectName="user",
            property="passwd",
            label="Password"
        )#
    </div>

    <div>#submitTag()#</div>
#endFormTag()#

</cfoutput>

Form Helpers

What we've done here is use form helpers to generate all of the form fields necessary for creating a new user in our database. It may feel a little strange using functions to generate form elements, but it will soon become clear why we're doing this. Trust us on this one… you'll love it!

To generate the form tag's action attribute, the startFormTag() function takes parameters similar to the linkTo()function that we introduced in the Beginner Tutorial: Hello World tutorial. We can pass in controller, action, key, and other route- and parameter-defined URLs just like we do with linkTo().

To end the form, we use the endFormTag() function. Easy enough.

The textField() and passwordField() helpers are similar. As you probably guessed, they create <input> elements with type="text" and type="password", respectively. And the submitTag() function creates an <input type="submit" /> element.

One thing you'll notice is the textField() and passwordField() functions accept arguments called objectName and property. As it turns out, this particular view code will throw an error because these functions are expecting an object named user. Let's fix that.

Supplying the Form with Data

All of the form helper calls in our view specify an objectName argument with a reference to a variable named user. That means that we need to supply our view code with an object called user. Because the controller is responsible for providing the views with data, we'll set it there.

Create a new ColdFusion component at app/controllers/Users.cfc.

As it turns out, our controller needs to provide the view with a blank user object (whose instance variable will also be called user in this case). In our new action, we will use the model() function to generate a new instance of the user model.

To get a blank set of properties in the model, we'll also call the generated model's new() method.

app/controllers/Users.cfc

component extends="Controller" {
    function config(){}

    function new() {
        user = model("user").new();
    }
}

Wheels will automatically know that we're talking about the users database table when we instantiate a user model. The convention: database tables are plural and their corresponding Wheels models are singular.

Why is our model name singular instead of plural? When we're talking about a single record in the users database, we represent that with an individual model object. So the users table contains many user objects. It just works better in conversation.

The Generated Form

Now when we run the URL at http://localhost/users/new, we'll see the form with the fields that we defined.

The HTML generated by your application will look something like this:

/users/new

<h1>New User</h1>

<form action="/users" method="post">
    <div>
        <label for="user-username">
            Username
            <input id="user-username" type="text" value="" name="user&#x5b;username&#x5d;">
        </label>
    </div>

    <div>
        <label for="user-email">
            Email
            <input id="user-email" type="text" value="" name="user&#x5b;email&#x5d;">
        </label>
    </div>

    <div>
        <label for="user-passwd">
            Password
            <input id="user-passwd" type="password" value="" name="user&#x5b;passwd&#x5d;">
        </label>
    </div>

    <div><input value="Save&#x20;changes" type="submit"></div>
</form>

So far we have a fairly well-formed, accessible form, without writing a bunch of repetitive markup.

Handling the Form Submission

Next, we'll code the create action in the controller to handle the form submission and save the new user to the database.

A basic way of doing this is using the model object's create() method:

app/controllers/Users.cfc

function create() {
    user = model("user").create(params.user);

    redirectTo(
        route="users",
        success="User created successfully."
    );
}

Because we used the objectName argument in the fields of our form, we can access the user data as a struct in the params struct.

There are more things that we can do in the create action to handle validation, but let's keep it simple in this tutorial.

Listing Users

Notice that our create action above redirects the user to the users index route using the redirectTo() function. We'll use this action to list all users in the system with "Edit" links. We'll also provide a link to the "New User" form that we just coded.

First, let's get the data that the listing needs. Create an action named index in the users controller like so:

app/controllers/Users.cfc

function index() {
    users = model("user").findAll(order="username");
}

This call to the model's findAll() method will return a query object of all users in the system. By using the method's order argument, we're also telling the database to order the records by username.

In the view at app/views/users/index.cfm, it's as simple as looping through the query and outputting the data

app/views/users/index.cfm

<cfoutput>

<h1>Users</h1>

<p>#linkTo(text="New User", route="newUser")#</p>

<table>
    <thead>
        <tr>
            <th>Username</th>
            <th>Email</th>
            <th colspan="2"></th>
        </tr>
    </thead>
    <tbody>
        <cfloop query="users">
            <tr>
                <td>
                    #EncodeForHtml(users.username)#
                </td>
                <td>
                    #EncodeForHtml(users.email)#
                </td>
                <td>
                    #linkTo(
                        text="Edit",
                        route="editUser",
                        key=users.id,
                        title="Edit #users.username#"
                    )#
                </td>
                <td>
                    #buttonTo(
                        text="Delete",
                        route="user",
                        key=users.id,
                        method="delete",
                        title="Delete #users.username#"
                    )#
                </td>
            </tr>
        </cfloop>
    </tbody>
</table>

</cfoutput>

When to use EncodeForHtml

You'll see references to EncodeForHtml in some of our examples that output data. This helps escape HTML code in data that attackers could use to embed inject harmful JavaScript. (This is commonly referred to as an "XSS attack," short for "Cross-site Scripting attack.")

A rule of thumb: you do not need to use EncodeForHtml when passing values into Wheels helpers like linkTo, buttonTo, startFormTag, textField, etc. However, you need to escape data that is displayed directly onto the page without a Wheels helper.

Editing Users

We'll now show another cool aspect of form helpers by creating a screen for editing users.

Coding the Edit Form

You probably noticed in the code listed above that we'll have an action for editing a single users record. We used the linkTo() form helper function to add an "Edit" button to the form. This action expects a key as well.

Because in the linkTo() form helper function we specified the parameter key, Wheels adds this parameter into the URL when generating the route.

Wheels will automatically add the provided 'key' from the URL to the params struct in the controllers edit() function.

Given the provided key, we'll have the action load the appropriate user object to pass on to the view:

app/controllers/Users.cfc

function edit() {
    user = model("user").findByKey(params.key);
}

The view at app/views/users/edit.cfm looks almost exactly the same as the view for creating a user:

app/views/users/edit.cfm

<cfoutput>

<h1>Edit User #EncodeForHtml(user.username)#</h1>

#startFormTag(route="user", key=user.key(), method="patch")#
    <div>
        #textField(objectName="user", property="username", label="Username")#
    </div>

    <div>
        #textField(objectName="user", property="email", label="Email")#
    </div>

    <div>
        #passwordField(
            objectName="user",
            property="passwd",
            label="Password"
        )#
    </div>

    <div>#submitTag()#</div>
#endFormTag()#

</cfoutput>

But an interesting thing happens. Because the form fields are bound to the user object via the form helpers' objectName arguments, the form will automatically provide default values based on the object's properties.

With the user model populated, we'll end up seeing code similar to this:

app/views/users/edit.cfm

<h1>Edit User Homer Simpson</h1>

<form action="/users/1" method="post">
    <input type="hidden" name="_method" value="patch">

    <div>
        <input type="hidden" name="user&#x5b;id&#x5d;" value="15">
    </div>

    <div>
        <label for="user-username">
            Name
            <input
                id="user-username"
                type="text"
                value="Homer Simpson"
                name="user&#x5b;username&#x5d;">
        </label>
    </div>

    <div>
        <label for="user-email">
            Email
            <input
                id="user-email"
                type="text"
                value="[email protected]"
                name="user&#x5b;email&#x5d;">
        </label>
    </div>

    <div>
        <label for="user-passwd">
            Password
            <input
                id="user-passwd"
                type="password"
                value="donuts.mmm"
                name="user&#x5b;passwd&#x5d;">
        </label>
    </div>

    <div><input value="Save&#x20;changes" type="submit"></div>
</form>

Pretty cool, huh?

Opportunities for Refactoring

There's a lot of repetition in the new and edit forms. You'd imagine that we could factor out most of this code into a single view file. To keep this tutorial from becoming a book, we'll just continue on knowing that this could be better.

Handing the Edit Form Submission

Now we'll create the update action. This will be similar to the create action, except it will be updating the user object:

app/controllers/Users.cfc

function update() {
    user = model("user").findByKey(params.key);
    user.update(params.user);

    redirectTo(
        route="editUser",
        key=user.id,
        success="User updated successfully."
    );
}

To update the user, simply call its update() method with the user struct passed from the form via params. It's that simple.

After the update, we'll add a success message using the Flash and send the end user back to the edit form in case they want to make more changes.

Deleting Users

Notice in our listing above that we have a delete action. Here's what it would look like:

app/controllers/Users.cfc

function delete() {
    user = model("user").findByKey(params.key);
    user.delete();

    redirectTo(
        route="users",
        success="User deleted successfully."
    );
}

We simply load the user using the model's findByKey() method and then call the object's delete() method. That's all there is to it.

Database Says Hello

We've shown you quite a few of the basics in getting a simple user database up and running. We hope that this has whet your appetite to see some of the power packed into the Wheels framework. There's plenty more.

Be sure to read on to some of the related chapters listed below to learn more about working with Wheels's ORM.

wheels generate resource

Generate a complete RESTful resource with model, controller, views, and routes.

Synopsis

wheels generate resource [name] [properties] [options]
wheels g resource [name] [properties] [options]

Description

The wheels generate resource command creates a complete RESTful resource including model, controller with all CRUD actions, views, routes, and optionally database migrations and tests. It's a comprehensive generator that sets up everything needed for a functioning resource.

Arguments

Argument

Description

Default

name

Resource name (singular)

Required

Options

Option

Description

Default

--api

Generate API-only resource (no views)

false

--tests

Generate associated tests

true

--migration

Generate database migration

true

belongs-to

Parent model relationships (comma-separated)

has-many

Child model relationships (comma-separated)

attributes

Model attributes (name:type,email:string)

--open

Open generated files

false

--scaffold

Generate with full CRUD operations

true

Examples

Basic Resource

wheels generate resource product attributes="name:string,price:float,description:text"

Generates:

Model: /models/Product.cfc
Controller: /controllers/Products.cfc
Views: /views/products/ (index, show, new, edit, _form)
Route: resources("products") in /config/routes.cfm
Migration: /app/migrator/migrations/[timestamp]_create_products.cfc
Tests: /tests/models/ProductTest.cfc, /tests/controllers/ProductsTest.cfc

API Resource

wheels generate resource product attributes="name:string,price:float" --api

Generates:

Model: /models/Product.cfc
Controller: /controllers/api/Products.cfc (JSON responses only)
Route: resources(name="products", except="new,edit") in API namespace
Migration: /app/migrator/migrations/[timestamp]_create_products.cfc
Tests: API-focused test files

Resource with Associations

wheels generate resource comment attributes="content:text,approved:boolean" belongs-to="post,user"

Generates nested structure with proper associations and routing.

Generated Files

Model

/models/Product.cfc:

component extends="Model" {
    
    function init() {
        // Properties
        property(name="name", sql="name");
        property(name="price", sql="price");
        property(name="description", sql="description");
        
        // Validations
        validatesPresenceOf(properties="name,price");
        validatesNumericalityOf(property="price", greaterThan=0);
        validatesLengthOf(property="name", maximum=255);
        
        // Callbacks
        beforeSave("sanitizeInput");
    }
    
    private function sanitizeInput() {
        this.name = Trim(this.name);
        if (StructKeyExists(this, "description")) {
            this.description = Trim(this.description);
        }
    }
    
}

Controller

/controllers/Products.cfc:

component extends="Controller" {
    
    function init() {
        // Filters
        filters(through="findProduct", only="show,edit,update,delete");
    }
    
    function index() {
        products = model("Product").findAll(order="createdAt DESC");
    }
    
    function show() {
        // Product loaded by filter
    }
    
    function new() {
        product = model("Product").new();
    }
    
    function create() {
        product = model("Product").new(params.product);
        
        if (product.save()) {
            flashInsert(success="Product was created successfully.");
            redirectTo(route="product", key=product.id);
        } else {
            renderView(action="new");
        }
    }
    
    function edit() {
        // Product loaded by filter
    }
    
    function update() {
        if (product.update(params.product)) {
            flashInsert(success="Product was updated successfully.");
            redirectTo(route="product", key=product.id);
        } else {
            renderView(action="edit");
        }
    }
    
    function delete() {
        if (product.delete()) {
            flashInsert(success="Product was deleted successfully.");
        } else {
            flashInsert(error="Product could not be deleted.");
        }
        redirectTo(route="products");
    }
    
    // Filters
    private function findProduct() {
        product = model("Product").findByKey(params.key);
        if (!IsObject(product)) {
            flashInsert(error="Product not found.");
            redirectTo(route="products");
        }
    }
    
}

Views

/views/products/index.cfm:

<h1>Products</h1>

<p>
    #linkTo(route="newProduct", text="New Product", class="btn btn-primary")#
</p>

<cfif products.recordCount>
    <table class="table table-striped">
        <thead>
            <tr>
                <th>Name</th>
                <th>Price</th>
                <th>Created</th>
                <th>Actions</th>
            </tr>
        </thead>
        <tbody>
            <cfoutput query="products">
                <tr>
                    <td>#linkTo(route="product", key=products.id, text=products.name)#</td>
                    <td>#dollarFormat(products.price)#</td>
                    <td>#dateFormat(products.createdAt, "mmm dd, yyyy")#</td>
                    <td>
                        #linkTo(route="editProduct", key=products.id, text="Edit", class="btn btn-sm btn-secondary")#
                        #linkTo(route="product", key=products.id, text="Delete", method="delete", confirm="Are you sure?", class="btn btn-sm btn-danger")#
                    </td>
                </tr>
            </cfoutput>
        </tbody>
    </table>
<cfelse>
    <p class="alert alert-info">No products found. #linkTo(route="newProduct", text="Create one now")#!</p>
</cfif>

/views/products/_form.cfm:

#errorMessagesFor("product")#

#startFormTag(route=formRoute, key=formKey, class="needs-validation")#
    
    <div class="mb-3">
        #textField(objectName="product", property="name", label="Product Name", class="form-control", required=true)#
    </div>
    
    <div class="mb-3">
        #numberField(objectName="product", property="price", label="Price", class="form-control", step="0.01", min="0", required=true)#
    </div>
    
    <div class="mb-3">
        #textArea(objectName="product", property="description", label="Description", class="form-control", rows=5)#
    </div>
    
    <div class="mb-3">
        #submitTag(value=submitValue, class="btn btn-primary")#
        #linkTo(route="products", text="Cancel", class="btn btn-secondary")#
    </div>
    
#endFormTag()#

Migration

/app/migrator/migrations/[timestamp]_create_products.cfc:

component extends="wheels.migrator.Migration" hint="Create products table" {
    
    function up() {
        transaction {
            createTable(name="products", force=true) {
                t.increments("id");
                t.string("name", limit=255, null=false);
                t.decimal("price", precision=10, scale=2, null=false);
                t.text("description");
                t.timestamps();
                t.index("name");
            };
        }
    }
    
    function down() {
        transaction {
            dropTable("products");
        }
    }
    
}

Routes

Added to /config/routes.cfm:

<cfset resources("products")>

API Resource Generation

API Controller

/controllers/api/Products.cfc:

component extends="Controller" {
    
    function init() {
        provides("json");
        filters(through="findProduct", only="show,update,delete");
    }
    
    function index() {
        products = model("Product").findAll(
            order="createdAt DESC",
            page=params.page ?: 1,
            perPage=params.perPage ?: 25
        );
        
        renderWith({
            data: products,
            meta: {
                page: products.currentPage,
                totalPages: products.totalPages,
                totalRecords: products.totalRecords
            }
        });
    }
    
    function show() {
        renderWith(product);
    }
    
    function create() {
        product = model("Product").new(params.product);
        
        if (product.save()) {
            renderWith(data=product, status=201);
        } else {
            renderWith(
                data={errors: product.allErrors()},
                status=422
            );
        }
    }
    
    function update() {
        if (product.update(params.product)) {
            renderWith(product);
        } else {
            renderWith(
                data={errors: product.allErrors()},
                status=422
            );
        }
    }
    
    function delete() {
        if (product.delete()) {
            renderWith(data={message: "Product deleted successfully"});
        } else {
            renderWith(
                data={error: "Could not delete product"},
                status=400
            );
        }
    }
    
    private function findProduct() {
        product = model("Product").findByKey(params.key);
        if (!IsObject(product)) {
            renderWith(
                data={error: "Product not found"},
                status=404
            );
        }
    }
    
}

Nested Resources

Generate Nested Resource

wheels generate resource review rating:integer comment:text parent=product

Nested Model

Includes association:

component extends="Model" {
    
    function init() {
        belongsTo("product");
        
        property(name="rating", sql="rating");
        property(name="comment", sql="comment");
        property(name="productId", sql="product_id");
        
        validatesPresenceOf(properties="rating,comment,productId");
        validatesNumericalityOf(property="rating", greaterThanOrEqualTo=1, lessThanOrEqualTo=5);
    }
    
}

Nested Routes

<cfset resources("products")>
    <cfset resources("reviews")>
</cfset>

Property Types

Supported Types

Type

Database Type

Validation

string

VARCHAR(255)

Length validation

text

TEXT

None by default

integer

INT

Numerical validation

float

DECIMAL

Numerical validation

decimal

DECIMAL

Numerical validation

boolean

BOOLEAN

Boolean validation

date

DATE

Date format validation

datetime

DATETIME

DateTime validation

time

TIME

Time validation

binary

BLOB

None

Property Options

wheels generate resource user \
  email:string:required:unique \
  age:integer:min=18:max=120 \
  bio:text:limit=1000 \
  isActive:boolean:default=true

Advanced Options

Skip Components

# Generate only model and migration
wheels generate resource product name:string --skip-controller --skip-views --skip-route

# Generate only controller and views
wheels generate resource product --skip-model --skip-migration

Namespace Resources

wheels generate resource admin/product name:string namespace=admin

Creates:

/controllers/admin/Products.cfc
/views/admin/products/
Namespaced routes

Custom Templates

wheels generate resource product name:string template=custom

Testing

Generated Tests

Model Test (/tests/models/ProductTest.cfc):

component extends="wheels.Test" {
    
    function setup() {
        super.setup();
        model("Product").deleteAll();
    }
    
    function test_valid_product_saves() {
        product = model("Product").new(
            name="Test Product",
            price=19.99,
            description="Test description"
        );
        
        assert(product.save());
        assert(product.id > 0);
    }
    
    function test_requires_name() {
        product = model("Product").new(price=19.99);
        
        assert(!product.save());
        assert(ArrayLen(product.errorsOn("name")) > 0);
    }
    
    function test_requires_positive_price() {
        product = model("Product").new(name="Test", price=-10);
        
        assert(!product.save());
        assert(ArrayLen(product.errorsOn("price")) > 0);
    }
    
}

Controller Test (/tests/controllers/ProductsTest.cfc):

component extends="wheels.Test" {
    
    function test_index_returns_products() {
        products = createProducts(3);
        
        result = processRequest(route="products", method="GET");
        
        assert(result.status == 200);
        assert(Find("Products", result.body));
        assert(FindNoCase(products[1].name, result.body));
    }
    
    function test_create_valid_product() {
        params = {
            product: {
                name: "New Product",
                price: 29.99,
                description: "New product description"
            }
        };
        
        result = processRequest(route="products", method="POST", params=params);
        
        assert(result.status == 302);
        assert(model("Product").count() == 1);
    }
    
}

Best Practices

Use singular names: product not products
Define all properties: Include types and validations
Add indexes: For frequently queried fields
Include tests: Don't skip test generation
Use namespaces: For admin or API resources
Follow conventions: Stick to RESTful patterns

Common Patterns

Soft Delete Resource

wheels generate resource product name:string deletedAt:datetime:nullable

Publishable Resource

wheels generate resource post title:string content:text publishedAt:datetime:nullable status:string:default=draft

User-Owned Resource

wheels generate resource task title:string userId:integer:belongsTo=user completed:boolean:default=false

Hierarchical Resource

wheels generate resource category name:string parentId:integer:nullable:belongsTo=category

Customization

Custom Resource Templates

Create in ~/.wheels/templates/resources/:

custom-resource/
├── model.cfc
├── controller.cfc
├── views/
│   ├── index.cfm
│   ├── show.cfm
│   ├── new.cfm
│   ├── edit.cfm
│   └── _form.cfm
└── migration.cfc

Template Variables

Available in templates:

${resourceName} - Singular name
${resourceNamePlural} - Plural name
${modelName} - Model class name
${controllerName} - Controller class name
${tableName} - Database table name
${properties} - Array of property definitions

wheels generate test

Generate test files for models, controllers, views, and other components.

Synopsis

wheels generate test [type] [name] [options]
wheels g test [type] [name] [options]

Description

The wheels generate test command creates test files for various components of your Wheels application. It generates appropriate test scaffolding based on the component type and includes common test cases to get you started.

Arguments

Argument

Description

Default

type

Type of test (model, controller, view, helper, route)

Required

name

Name of the component to test

Required

Options

Option

Description

Default

--methods

Specific methods to test

All methods

--integration

Generate integration tests

false

--coverage

Include coverage setup

false

--fixtures

Generate test fixtures

true

--force

Overwrite existing files

false

--help

Show help information

Examples

Model Test

wheels generate test model product

Generates /tests/models/ProductTest.cfc:

component extends="wheels.Test" {
    
    function setup() {
        super.setup();
        // Clear test data
        model("Product").deleteAll();
        
        // Setup test fixtures
        variables.validProduct = {
            name: "Test Product",
            price: 19.99,
            description: "Test product description"
        };
    }
    
    function teardown() {
        super.teardown();
        // Clean up after tests
        model("Product").deleteAll();
    }
    
    // Validation Tests
    
    function test_valid_product_saves_successfully() {
        // Arrange
        product = model("Product").new(variables.validProduct);
        
        // Act
        result = product.save();
        
        // Assert
        assert(result, "Product should save successfully");
        assert(product.id > 0, "Product should have an ID after saving");
    }
    
    function test_product_requires_name() {
        // Arrange
        product = model("Product").new(variables.validProduct);
        product.name = "";
        
        // Act
        result = product.save();
        
        // Assert
        assert(!result, "Product should not save without name");
        assert(ArrayLen(product.errorsOn("name")) > 0, "Should have error on name");
    }
    
    function test_product_requires_positive_price() {
        // Arrange
        product = model("Product").new(variables.validProduct);
        product.price = -10;
        
        // Act
        result = product.save();
        
        // Assert
        assert(!result, "Product should not save with negative price");
        assert(ArrayLen(product.errorsOn("price")) > 0, "Should have error on price");
    }
    
    function test_product_name_must_be_unique() {
        // Arrange
        product1 = model("Product").create(variables.validProduct);
        product2 = model("Product").new(variables.validProduct);
        
        // Act
        result = product2.save();
        
        // Assert
        assert(!result, "Should not save duplicate product name");
        assert(ArrayLen(product2.errorsOn("name")) > 0, "Should have uniqueness error");
    }
    
    // Association Tests
    
    function test_product_has_many_reviews() {
        // Arrange
        product = model("Product").create(variables.validProduct);
        review = product.createReview(rating=5, comment="Great product!");
        
        // Act
        reviews = product.reviews();
        
        // Assert
        assert(reviews.recordCount == 1, "Product should have one review");
        assert(reviews.rating == 5, "Review rating should be 5");
    }
    
    // Callback Tests
    
    function test_before_save_sanitizes_input() {
        // Arrange
        product = model("Product").new(variables.validProduct);
        product.name = "  Test Product  ";
        
        // Act
        product.save();
        
        // Assert
        assert(product.name == "Test Product", "Name should be trimmed");
    }
    
    // Scope Tests
    
    function test_active_scope_returns_only_active_products() {
        // Arrange
        activeProduct = model("Product").create(
            variables.validProduct & {isActive: true}
        );
        inactiveProduct = model("Product").create(
            name="Inactive Product",
            price=29.99,
            isActive=false
        );
        
        // Act
        activeProducts = model("Product").active();
        
        // Assert
        assert(activeProducts.recordCount == 1, "Should have one active product");
        assert(activeProducts.id == activeProduct.id, "Should return active product");
    }
    
    // Method Tests
    
    function test_calculate_discount_price() {
        // Arrange
        product = model("Product").create(variables.validProduct);
        
        // Act
        discountPrice = product.calculateDiscountPrice(0.20); // 20% discount
        
        // Assert
        expected = product.price * 0.80;
        assert(discountPrice == expected, "Discount price should be 80% of original");
    }
    
    // Integration Tests
    
    function test_product_lifecycle() {
        transaction {
            // Create
            product = model("Product").new(variables.validProduct);
            assert(product.save(), "Should create product");
            productId = product.id;
            
            // Read
            foundProduct = model("Product").findByKey(productId);
            assert(IsObject(foundProduct), "Should find product");
            assert(foundProduct.name == variables.validProduct.name, "Should have correct name");
            
            // Update
            foundProduct.price = 24.99;
            assert(foundProduct.save(), "Should update product");
            
            // Verify update
            updatedProduct = model("Product").findByKey(productId);
            assert(updatedProduct.price == 24.99, "Price should be updated");
            
            // Delete
            assert(updatedProduct.delete(), "Should delete product");
            
            // Verify deletion
            deletedProduct = model("Product").findByKey(productId);
            assert(!IsObject(deletedProduct), "Product should not exist");
            
            // Rollback transaction
            transaction action="rollback";
        }
    }
    
}

Controller Test

wheels generate test controller products

Generates /tests/controllers/ProductsTest.cfc:

View Test

wheels generate test view products --name=index

Generates a test for the products/index view.

CRUD Tests

wheels generate test controller products --crud

Generates complete CRUD test methods for the controller.

component extends="wheels.Test" {
    
    function setup() {
        super.setup();
        // Setup test data
        model("Product").deleteAll();
        
        variables.testProducts = [];
        for (i = 1; i <= 3; i++) {
            ArrayAppend(variables.testProducts, 
                model("Product").create(
                    name="Product #i#",
                    price=19.99 * i,
                    description="Description #i#"
                )
            );
        }
    }
    
    function teardown() {
        super.teardown();
        model("Product").deleteAll();
    }
    
    // Action Tests
    
    function test_index_returns_all_products() {
        // Act
        result = processRequest(route="products", method="GET");
        
        // Assert
        assert(result.status == 200, "Should return 200 status");
        assert(Find("<h1>Products</h1>", result.body), "Should have products heading");
        
        for (product in variables.testProducts) {
            assert(Find(product.name, result.body), "Should display product: #product.name#");
        }
    }
    
    function test_show_displays_product_details() {
        // Arrange
        product = variables.testProducts[1];
        
        // Act
        result = processRequest(route="product", key=product.id, method="GET");
        
        // Assert
        assert(result.status == 200, "Should return 200 status");
        assert(Find(product.name, result.body), "Should display product name");
        assert(Find(DollarFormat(product.price), result.body), "Should display formatted price");
    }
    
    function test_show_returns_404_for_invalid_product() {
        // Act
        result = processRequest(route="product", key=99999, method="GET");
        
        // Assert
        assert(result.status == 302, "Should redirect");
        assert(result.flash.error == "Product not found.", "Should have error message");
    }
    
    function test_new_displays_form() {
        // Act
        result = processRequest(route="newProduct", method="GET");
        
        // Assert
        assert(result.status == 200, "Should return 200 status");
        assert(Find("<form", result.body), "Should have form");
        assert(Find('name="product[name]"', result.body), "Should have name field");
        assert(Find('name="product[price]"', result.body), "Should have price field");
    }
    
    function test_create_with_valid_data() {
        // Arrange
        params = {
            product: {
                name: "New Test Product",
                price: 39.99,
                description: "New product description"
            }
        };
        
        // Act
        result = processRequest(route="products", method="POST", params=params);
        
        // Assert
        assert(result.status == 302, "Should redirect after creation");
        assert(result.flash.success == "Product was created successfully.", "Should have success message");
        
        // Verify product was created
        newProduct = model("Product").findOne(where="name='New Test Product'");
        assert(IsObject(newProduct), "Product should be created");
        assert(newProduct.price == 39.99, "Should have correct price");
    }
    
    function test_create_with_invalid_data() {
        // Arrange
        params = {
            product: {
                name: "",
                price: -10,
                description: "Invalid product"
            }
        };
        
        // Act
        result = processRequest(route="products", method="POST", params=params);
        
        // Assert
        assert(result.status == 200, "Should render form again");
        assert(Find("error", result.body), "Should display errors");
        assert(model("Product").count(where="description='Invalid product'") == 0, 
               "Should not create invalid product");
    }
    
    function test_edit_displays_form_with_product_data() {
        // Arrange
        product = variables.testProducts[1];
        
        // Act
        result = processRequest(route="editProduct", key=product.id, method="GET");
        
        // Assert
        assert(result.status == 200, "Should return 200 status");
        assert(Find('value="#product.name#"', result.body), "Should pre-fill name");
        assert(Find(ToString(product.price), result.body), "Should pre-fill price");
    }
    
    function test_update_with_valid_data() {
        // Arrange
        product = variables.testProducts[1];
        params = {
            product: {
                name: "Updated Product Name",
                price: 49.99
            }
        };
        
        // Act
        result = processRequest(route="product", key=product.id, method="PUT", params=params);
        
        // Assert
        assert(result.status == 302, "Should redirect after update");
        assert(result.flash.success == "Product was updated successfully.", "Should have success message");
        
        // Verify update
        updatedProduct = model("Product").findByKey(product.id);
        assert(updatedProduct.name == "Updated Product Name", "Name should be updated");
        assert(updatedProduct.price == 49.99, "Price should be updated");
    }
    
    function test_delete_removes_product() {
        // Arrange
        product = variables.testProducts[1];
        initialCount = model("Product").count();
        
        // Act
        result = processRequest(route="product", key=product.id, method="DELETE");
        
        // Assert
        assert(result.status == 302, "Should redirect after deletion");
        assert(result.flash.success == "Product was deleted successfully.", "Should have success message");
        assert(model("Product").count() == initialCount - 1, "Should have one less product");
        assert(!IsObject(model("Product").findByKey(product.id)), "Product should be deleted");
    }
    
    // Filter Tests
    
    function test_authentication_required_for_protected_actions() {
        // Test that certain actions require authentication
        protectedRoutes = [
            {route: "newProduct", method: "GET"},
            {route: "products", method: "POST"},
            {route: "editProduct", key: variables.testProducts[1].id, method: "GET"},
            {route: "product", key: variables.testProducts[1].id, method: "PUT"},
            {route: "product", key: variables.testProducts[1].id, method: "DELETE"}
        ];
        
        for (route in protectedRoutes) {
            // Act without authentication
            result = processRequest(argumentCollection=route);
            
            // Assert
            assert(result.status == 302, "Should redirect unauthenticated user");
            assert(result.redirectUrl contains "login", "Should redirect to login");
        }
    }
    
    // Helper method for processing requests
    private function processRequest(
        required string route,
        string method = "GET",
        struct params = {},
        numeric key = 0
    ) {
        local.args = {
            route: arguments.route,
            method: arguments.method,
            params: arguments.params
        };
        
        if (arguments.key > 0) {
            local.args.key = arguments.key;
        }
        
        return $processRequest(argumentCollection=local.args);
    }
    
}

View Test

wheels generate test view products/index

Generates /tests/views/products/IndexTest.cfc:

component extends="wheels.Test" {
    
    function setup() {
        super.setup();
        // Create test data
        variables.products = QueryNew(
            "id,name,price,createdAt",
            "integer,varchar,decimal,timestamp"
        );
        
        for (i = 1; i <= 3; i++) {
            QueryAddRow(variables.products, {
                id: i,
                name: "Product #i#",
                price: 19.99 * i,
                createdAt: Now()
            });
        }
    }
    
    function test_index_view_renders_product_list() {
        // Act
        result = $renderView(
            view="/products/index",
            products=variables.products,
            layout=false
        );
        
        // Assert
        assert(Find("<h1>Products</h1>", result), "Should have products heading");
        assert(Find("<table", result), "Should have products table");
        assert(Find("Product 1", result), "Should display first product");
        assert(Find("Product 2", result), "Should display second product");
        assert(Find("Product 3", result), "Should display third product");
    }
    
    function test_index_view_shows_empty_state() {
        // Arrange
        emptyQuery = QueryNew("id,name,price,createdAt");
        
        // Act
        result = $renderView(
            view="/products/index",
            products=emptyQuery,
            layout=false
        );
        
        // Assert
        assert(Find("No products found", result), "Should show empty state message");
        assert(Find("Create one now", result), "Should have create link");
        assert(!Find("<table", result), "Should not show table when empty");
    }
    
    function test_index_view_formats_prices_correctly() {
        // Act
        result = $renderView(
            view="/products/index",
            products=variables.products,
            layout=false
        );
        
        // Assert
        assert(Find("$19.99", result), "Should format first price");
        assert(Find("$39.98", result), "Should format second price");
        assert(Find("$59.97", result), "Should format third price");
    }
    
    function test_index_view_includes_action_links() {
        // Act
        result = $renderView(
            view="/products/index",
            products=variables.products,
            layout=false
        );
        
        // Assert
        assert(Find("New Product", result), "Should have new product link");
        assert(FindNoCase("href=""/products/new""", result), "New link should be correct");
        
        // Check action links for each product
        for (row in variables.products) {
            assert(Find("View</a>", result), "Should have view link");
            assert(Find("Edit</a>", result), "Should have edit link");
            assert(Find("Delete</a>", result), "Should have delete link");
        }
    }
    
    function test_index_view_with_pagination() {
        // Arrange
        paginatedProducts = Duplicate(variables.products);
        paginatedProducts.currentPage = 2;
        paginatedProducts.totalPages = 5;
        paginatedProducts.totalRecords = 50;
        
        // Act
        result = $renderView(
            view="/products/index",
            products=paginatedProducts,
            layout=false
        );
        
        // Assert
        assert(Find("class=""pagination""", result), "Should have pagination");
        assert(Find("Previous", result), "Should have previous link");
        assert(Find("Next", result), "Should have next link");
        assert(Find("Page 2 of 5", result), "Should show current page");
    }
    
    function test_index_view_escapes_html() {
        // Arrange
        productsWithHtml = QueryNew("id,name,price,createdAt");
        QueryAddRow(productsWithHtml, {
            id: 1,
            name: "<script>alert('XSS')</script>",
            price: 19.99,
            createdAt: Now()
        });
        
        // Act
        result = $renderView(
            view="/products/index",
            products=productsWithHtml,
            layout=false
        );
        
        // Assert
        assert(!Find("<script>alert('XSS')</script>", result), 
               "Should not have unescaped script tag");
        assert(Find("&lt;script&gt;", result), "Should have escaped HTML");
    }
    
}

Integration Test

wheels generate test controller products --integration

Generates additional integration tests:

component extends="wheels.Test" {
    
    function test_complete_product_workflow() {
        transaction {
            // 1. View product list (empty)
            result = $visit(route="products");
            assert(result.status == 200);
            assert(Find("No products found", result.body));
            
            // 2. Navigate to new product form
            result = $click("Create one now");
            assert(result.status == 200);
            assert(Find("<form", result.body));
            
            // 3. Submit new product form
            result = $submitForm({
                "product[name]": "Integration Test Product",
                "product[price]": "29.99",
                "product[description]": "Test description"
            });
            assert(result.status == 302);
            assert(result.flash.success);
            
            // 4. View created product
            product = model("Product").findOne(order="id DESC");
            result = $visit(route="product", key=product.id);
            assert(result.status == 200);
            assert(Find("Integration Test Product", result.body));
            
            // 5. Edit product
            result = $click("Edit");
            assert(Find('value="Integration Test Product"', result.body));
            
            result = $submitForm({
                "product[name]": "Updated Product",
                "product[price]": "39.99"
            });
            assert(result.status == 302);
            
            // 6. Verify update
            result = $visit(route="product", key=product.id);
            assert(Find("Updated Product", result.body));
            assert(Find("$39.99", result.body));
            
            // 7. Delete product
            result = $click("Delete", confirm=true);
            assert(result.status == 302);
            assert(result.flash.success contains "deleted");
            
            // 8. Verify deletion
            assert(!IsObject(model("Product").findByKey(product.id)));
            
            transaction action="rollback";
        }
    }
    
}

Test Types

Model Tests

Focus on:

Validations
Associations
Callbacks
Scopes
Custom methods
Data integrity

Controller Tests

Focus on:

Action responses
Parameter handling
Authentication/authorization
Flash messages
Redirects
Error handling

View Tests

Focus on:

Content rendering
Data display
HTML structure
Escaping/security
Conditional display
Helpers usage

Helper Tests

wheels generate test helper format

component extends="wheels.Test" {
    
    function test_format_currency() {
        assert(formatCurrency(19.99) == "$19.99");
        assert(formatCurrency(1000) == "$1,000.00");
        assert(formatCurrency(0) == "$0.00");
        assert(formatCurrency(-50.5) == "-$50.50");
    }
    
}

Route Tests

wheels generate test route products

component extends="wheels.Test" {
    
    function test_products_routes() {
        // Test route resolution
        assert($resolveRoute("/products") == {controller: "products", action: "index"});
        assert($resolveRoute("/products/new") == {controller: "products", action: "new"});
        assert($resolveRoute("/products/123") == {controller: "products", action: "show", key: "123"});
        
        // Test route generation
        assert(urlFor(route="products") == "/products");
        assert(urlFor(route="product", key=123) == "/products/123");
        assert(urlFor(route="newProduct") == "/products/new");
    }
    
}

Test Fixtures

Generate Fixtures

wheels generate test model product --fixtures

Creates /tests/fixtures/products.cfc:

component {
    
    function load() {
        // Clear existing data
        model("Product").deleteAll();
        
        // Load fixture data
        fixtures = [
            {
                name: "Widget",
                price: 19.99,
                description: "Standard widget",
                categoryId: 1,
                isActive: true
            },
            {
                name: "Gadget",
                price: 29.99,
                description: "Premium gadget",
                categoryId: 2,
                isActive: true
            },
            {
                name: "Doohickey",
                price: 9.99,
                description: "Budget doohickey",
                categoryId: 1,
                isActive: false
            }
        ];
        
        for (fixture in fixtures) {
            model("Product").create(fixture);
        }
        
        return fixtures;
    }
    
    function loadWithAssociations() {
        products = load();
        
        // Add reviews
        model("Review").create(
            productId: products[1].id,
            rating: 5,
            comment: "Excellent product!"
        );
        
        return products;
    }
    
}

Test Helpers

Custom Assertions

// In test file
function assertProductValid(required any product) {
    assert(IsObject(arguments.product), "Product should be an object");
    assert(arguments.product.id > 0, "Product should have valid ID");
    assert(Len(arguments.product.name), "Product should have name");
    assert(arguments.product.price > 0, "Product should have positive price");
}

function assertHasError(required any model, required string property) {
    local.errors = arguments.model.errorsOn(arguments.property);
    assert(ArrayLen(local.errors) > 0, 
           "Expected error on #arguments.property# but found none");
}

Test Data Builders

function createTestProduct(struct overrides = {}) {
    local.defaults = {
        name: "Test Product #CreateUUID()#",
        price: RandRange(10, 100) + (RandRange(0, 99) / 100),
        description: "Test description",
        isActive: true
    };
    
    StructAppend(local.defaults, arguments.overrides, true);
    
    return model("Product").create(local.defaults);
}

function createTestUser(struct overrides = {}) {
    local.defaults = {
        email: "test-#CreateUUID()#@example.com",
        password: "password123",
        firstName: "Test",
        lastName: "User"
    };
    
    StructAppend(local.defaults, arguments.overrides, true);
    
    return model("User").create(local.defaults);
}

Running Tests

Run all tests

wheels test

Run specific test file

wheels test app tests/models/ProductTest.cfc

Run specific test method

wheels test app tests/models/ProductTest.cfc::test_product_requires_name

Run with coverage

wheels test --coverage

Best Practices

Test in isolation: Each test should be independent
Use descriptive names: Test names should explain what they test
Follow AAA pattern: Arrange, Act, Assert
Clean up data: Use setup/teardown or transactions
Test edge cases: Empty data, nulls, extremes
Mock external services: Don't rely on external APIs
Keep tests fast: Optimize slow tests
Test one thing: Each test should verify one behavior
Use fixtures wisely: Share common test data
Run tests frequently: Before commits and in CI

Common Testing Patterns

Testing Private Methods

function test_private_method_through_public_interface() {
    // Don't test private methods directly
    // Test them through public methods that use them
    product = model("Product").new(name: "  Test  ");
    product.save(); // Calls private sanitize method
    assert(product.name == "Test");
}

Testing Time-Dependent Code

function test_expiration_date() {
    // Use specific dates instead of Now()
    testDate = CreateDate(2024, 1, 1);
    product = model("Product").new(
        expiresAt: DateAdd("d", 30, testDate)
    );
    
    // Test with mocked current date
    request.currentDate = testDate;
    assert(!product.isExpired());
    
    request.currentDate = DateAdd("d", 31, testDate);
    assert(product.isExpired());
}

Testing Randomness

function test_random_discount() {
    // Test the range, not specific values
    product = model("Product").new(price: 100);
    
    for (i = 1; i <= 100; i++) {
        discount = product.getRandomDiscount();
        assert(discount >= 0.05 && discount <= 0.25, 
               "Discount should be between 5% and 25%");
    }
}

3.0.0-SNAPSHOT

INTRODUCTION

Getting Started

Install CommandBox

Install the wheels-cli CommandBox Module

Start a new Application using the Wizard

Start a New Application Using the Command Line

Running Local Development Servers

Starting a local development server

Using custom host names

Controlling local servers

Specifying different CF engines

Tutorial: Wheels, AJAX, and You

A Simple Example

AJAX in Wheels Explained

Manual Installation

Manual Installation

1. Download Wheels

2. Setup the Website

3. Setup the Database (Optional)

4. Test It

Screencasts

Wheels 2.x

Wheels 1.x

CRUD series

"Building a Social Network"

Other

Command Line Tools

Core Commands

wheels init

Synopsis

Description

Arguments

Options

Interactive Prompts

Examples

Initialize current directory

What It Does

Generated Files

server.json

box.json

Prerequisites

Notes

See Also

wheels info

Synopsis

Description

Arguments

Options

Output

Example Output

Use Cases

Notes

See Also

wheels reload

Synopsis

Description

Arguments

Options

Reload Modes

Development Mode

Testing Mode

Maintenance Mode

Production Mode

Examples

Basic reload (development mode)

Reload in production mode

Using the alias

Reload for testing

Security

Configuration

Notes

Common Issues

See Also

Code Generation

Database Commands

Database Operations

wheels db create

Synopsis

Description