File Uploads in Wheels 4.0, the Idiomatic Way

[bpamiri]

A net-new how-to in the post-GA series — the first one covering file uploads, because it's the question that comes up the moment someone tries to add an avatar field and goes looking for a Wheels equivalent of Active Storage.

Read: https://blog.wheels.dev/posts/file-uploads-in-wheels-4

The short version: Wheels 4.0 has no dedicated file-upload abstraction, and the post argues that's a deliberate, honest design rather than a gap. Grep vendor/wheels/ for a storage layer — storeFile, mountUploader, activeStorage — and you get nothing; the word "upload" appears only in comments and doc strings, never as an abstraction. cffile/fileUpload() appear zero times in vendor/wheels/controller/. The framework owns the two ends that need framework knowledge and leaves the middle to plain CFML.

The flow the post walks, end to end

Building avatar uploads for a User:

1. The form — fileField(objectName="user", property="avatar") (bound, emits the bracket name user[avatar]) or fileFieldTag(name="document") (unbound, plain name). The field name is the contract with the controller.
2. The multipart flag — startFormTag(multipart=true) to get enctype="multipart/form-data".
3. The controller — native cffile action="upload" with nameConflict="makeUnique", then copy cffile.serverFile / .fileSize / .contentType onto params.user.
4. The model — validatesFormatOf over the stored path string + a custom validate() callback for size and MIME, because validators can't inspect a multipart upload.
5. The download — sendFile, the one direction with a real Wheels helper, with built-in path-traversal protection.

The one thing everyone gets wrong

startFormTag does not detect a fileField and does not add the multipart enctype on its own. The framework default is multipart=false. The actual logic is:

if (!StructKeyExists(arguments, "enctype") && arguments.multipart) {
    arguments.enctype = "multipart/form-data";
}

Forget multipart=true and the browser posts the file input as a plain-text filename, params has no file, cffile finds nothing, and the framework throws no error. The upload fails silently while everything looks correct. The post leads with this because it's the bug that costs people an hour every time.

Corroboration from the framework itself

The framework's own AI-reference doc (vendor/wheels/public/views/ai.cfm) documents the "File Uploads" pattern using native fileUpload(expandPath('./public/uploads/'), 'avatar', 'image/*', 'MakeUnique') reading .serverFile, paired with startFormTag(enctype='multipart/form-data'). It's illustrative snippet text in a JSON blob (not executed code), but it's the framework telling you in its own voice that native CFML is the intended upload path.

A few sharp edges the post details

• The file is on disk before the model validates. cffile writes the bytes in the controller; validation runs afterward. A validation failure stops the DB row but leaves an orphan file. Reject-and-delete belongs in the controller or the validate method.
• Path-traversal safety on the way IN is your responsibility. sendFile guards the download path (throws Wheels.InvalidPath on .., strips null bytes), but nothing guards the upload destination. nameConflict="makeUnique" is your friend.
• $file() in Global.cfc is NOT an upload API. It's an internal cffile wrapper for a cross-engine attributeCollection gotcha. Don't let an assistant present it as a public upload helper.
• Match the field name across all three sites — fileField → user[avatar] → cffile fileField="user[avatar]" → StructKeyExists(form, "user[avatar]"). Mismatch is another silent failure.

Discussion

If you've shipped uploads on Wheels, I'd like to hear how you handle the storage-location question (in-docroot vs. out, object storage), and whether you've built any conventions around orphan cleanup or per-user authorization on sendFile. There's deliberately no framework convention enforcing a storage location — curious what patterns people have settled on. Feedback on what's missing or what a follow-up should cover is welcome in this thread.