Validations Beyond Presence: Conditional Rules, Custom Validators, and Enum Integration

[bpamiri]

The first validation everyone writes is validatesPresenceOf("email"). It's the right first move — but presence is the floor, not the ceiling. The day you ship a real signup form you need the email to look like an email, to be unique within an account (not globally), to match a confirmation field but only on create, and you need status to be one of a closed set — never wat.

This post walks the entire Wheels 4.0 validation surface through one worked User/Post model.

Read: https://blog.wheels.dev/posts/validations-conditional-enum

What's in it

The validator surface. All the high-level validators side by side in one model, with a table mapping each to its exact behavior and default message:

• validatesUniquenessOf with scope for unique-per-tenant fields — and why it's an application-level findAll(), not a DB constraint (back it with a real unique index).
• validatesFormatOf in both modes: regEx for arbitrary patterns, type for the built-in IsValid() checks (email, URL, UUID, creditcard, ssn, zipcode, and the rest).
• validatesLengthOf with within="3,20", and why a 0 bound means "not set."
• validatesInclusionOf / validatesExclusionOf (both require list).
• validatesConfirmationOf — and the surprise that its error lands on the virtual <property>Confirmation property, not the base one.

Conditional validation. condition, unless, and when. The post is emphatic about one thing: condition and unless are a fixed-grammar string parser (this.prop, this.method(), bare method(), !negation, eq/neq/lt/lte/gt/gte comparisons) — not CFML's Evaluate() and not a closure. A malformed expression throws Wheels.InvalidValidationCondition in development but is logged and silently skipped in production, which means the validation quietly stops running.

Custom validators. validate(), validateOnCreate(), validateOnUpdate() register a method name; the method fails by calling addError() / addErrorToBase(). The method's return value is ignored — return false on bad data does nothing. This is the single most common mistake.

enum() integration. One call auto-registers validatesInclusionOf (with allowBlank=true), generates is<Name>() boolean checkers, and creates a parameterized query scope per value. Because it allows blanks, you pair it with validatesPresenceOf when the column is required. Registration-time guards reject bad property names and stored values outside [A-Za-z0-9_- .].

Reading errors correctly. errorsOn() returns an array of {property, message, name} structs, not strings — loop and read .message. Plus errorsOnBase, allErrors, hasErrors, errorCount, and clearErrors with their property/name filters, and how the optional name tag lets you surgically clear one error.

It ends with a sharp-edges section drawn straight from the framework source: scoped uniqueness races, presence being skipped on columns with a DB default, allowBlank defaulting to false everywhere it exists (and not existing on presence/confirmation), and the all-named-args rule that prevents the #1 Wheels error.

Discussion

• How are you handling unique-per-tenant constraints today — validatesUniquenessOf(scope=...) plus a composite unique index, or something else?
• Anyone bitten by the production-silent-skip behavior of an unparseable condition expression? Would a louder failure mode (or a startup-time grammar check on every condition string) be worth it?
• Do you lean on enum() for closed-set fields, or still hand-write validatesInclusionOf + scopes? What's missing from enum() that would tip you over?

Read the full post: https://blog.wheels.dev/posts/validations-conditional-enum