BoxLang 🚀 A New JVM Dynamic Language Learn More...

ColdBox Validation

v4.4.0+26 Modules


Copyright Since 2005 ColdBox Platform by Luis Majano and Ortus Solutions, Corp
www.coldbox.org | www.ortussolutions.com


WELCOME TO THE COLDBOX VALIDATION MODULE

This module is a server side rules validation engine that can provide you with a unified approach to object, struct and form validation. You can construct validation constraint rules and then tell the engine to validate them accordingly.

LICENSE

Apache License, Version 2.0.

SYSTEM REQUIREMENTS

  • Lucee 5.x+
  • Adobe ColdFusion 2018+

Installation

Leverage CommandBox to install:

box install cbvalidation

The module will register several objects into WireBox using the @cbvalidation namespace. The validation manager is registered as ValidationManager@cbvalidation. It will also register several helper methods that can be used throughout the ColdBox application: validate(), validateOrFail(), getValidationManager()

Mixins

The module will also register several methods in your handlers/interceptors/layouts/views

/**
 * Validate an object or structure according to the constraints rules.
 *
 * @target An object or structure to validate
 * @fields The fields to validate on the target. By default, it validates on all fields
 * @constraints A structure of constraint rules or the name of the shared constraint rules to use for validation
 * @locale The i18n locale to use for validation messages
 * @excludeFields The fields to exclude from the validation
 * @includeFields The fields to include in the validation
 * @profiles If passed, a list of profile names to use for validation constraints
 *
 * @return cbvalidation.model.result.IValidationResult
 */
function validate()

/**
 * Validate an object or structure according to the constraints rules and throw an exception if the validation fails.
 * The validation errors will be contained in the `extendedInfo` of the exception in JSON format
 *
 * @target An object or structure to validate
 * @fields The fields to validate on the target. By default, it validates on all fields
 * @constraints A structure of constraint rules or the name of the shared constraint rules to use for validation
 * @locale The i18n locale to use for validation messages
 * @excludeFields The fields to exclude from the validation
 * @includeFields The fields to include in the validation
 * @profiles If passed, a list of profile names to use for validation constraints
 *
 * @return The validated object or the structure fields that where validated
 * @throws ValidationException
 */
function validateOrFail()

/**
 * Retrieve the application's configured Validation Manager
 */
function getValidationManager()

/**
 * Verify if the target value has a value
 * Checks for nullness or for length if it's a simple value, array, query, struct or object.
 */
boolean function validateHasValue( any targetValue )

/**
 * Check if a value is null or is a simple value and it's empty
 *
 * @targetValue the value to check for nullness/emptyness
 */
boolean function validateIsNullOrEmpty( any targetValue )

/**
 * This method mimics the Java assert() function, where it evaluates the target to a boolean value and it must be true
 * to pass and return a true to you, or throw an `AssertException`
 *
 * @target The tareget to evaluate for being true
 * @message The message to send in the exception
 *
 * @throws AssertException if the target is a false or null value
 * @return True, if the target is a non-null value. If false, then it will throw the `AssertError` exception
 */
boolean function assert( target, message="" )

Settings

Here are the module settings you can place in your ColdBox.cfc by using the cbvalidation settings structure in the modulesettings

modulesettings = {
	cbValidation = {
		// The third-party validation manager to use, by default it uses CBValidation.
		manager = "class path",

		// You can store global constraint rules here with unique names
		sharedConstraints = {
			name = {
				field = { constraints here }
			}
		}
	}
}

You can read more about ColdBox Validation here: - https://coldbox-validation.ortusbooks.com/

Constraints

Please check out the docs for the latest on constraints: https://coldbox-validation.ortusbooks.com/overview/valid-constraints. Constraints rely on rules you apply to incoming fields of data. They can be created on objects or stored wherever you like, as long as you pass them to the validation methods.

Each property can have one or more constraints attached to it. In an object you can create a this.constraints and declare them by the fields you like:

this.constraints = {

	propertyName = {
        // The field under validation must be yes, on, 1, or true. This is useful for validating "Terms of Service" acceptance.
        accepted : any value

        // The field under validation must be a date after the set targetDate
        after : targetDate

        // The field under validation must be a date after or equal the set targetDate
        afterOrEqual : targetDate

        // The field must be alphanumeric ONLY
        alpha : any value

        // The field under validation is an array and all items must pass this validation as well
        arrayItem : {
            // All the constraints to validate the items with
        }

        // The field under validation must be a date before the set targetDate
        before : targetDate

        // The field under validation must be a date before or equal the set targetDate
        beforeOrEqual : targetDate

        // The field under validation must be a date that is equal the set targetDate
        dateEquals : targetDate

        // discrete math modifiers
        discrete : (gt,gte,lt,lte,eq,neq):value

        // value in list
        inList : list

        // max value
        max : value

        // Validation method to use in the target object must return boolean accept the incoming value and target object
        method : methodName

        // min value
        min : value

        // range is a range of values the property value should exist in
        range : eg: 1..10 or 5..-5

        // regex validation
        regex : valid no case regex

        // required field or not, includes null values
        required : boolean [false]

        // The field under validation must be present and not empty if the `anotherfield` field is equal to the passed `value`.
        requiredIf : {
            anotherfield:value, anotherfield:value
        }

        // The field under validation must be present and not empty unless the `anotherfield` field is equal to the passed
        requiredUnless : {
            anotherfield:value, anotherfield:value
        }

        // same as but with no case
        sameAsNoCase : propertyName

        // same as another property
        sameAs : propertyName

        // size or length of the value which can be a (struct,string,array,query)
        size  : numeric or range, eg: 10 or 6..8

        // specific type constraint, one in the list.
        type  : (alpha,array,binary,boolean,component,creditcard,date,email,eurodate,float,GUID,integer,ipaddress,json,numeric,query,ssn,string,struct,telephone,url,usdate,UUID,xml,zipcode),

        // UDF to use for validation, must return boolean accept the incoming value and target object, validate(value,target):boolean
        udf = variables.UDF or this.UDF or a closure.

        // Check if a column is unique in the database
        unique = {
            table : The table name,
            column : The column to check, defaults to the property field in check
        }

        // Custom validator, must implement coldbox.system.validation.validators.IValidator
        validator : path or wirebox id, example: 'mypath.MyValidator' or 'id:MyValidator'
	}

}

Constraint Profiles

You can also create profiles or selections of fields that will be targeted for validation if you are defining the constraints in objects. All you do is create a key called: this.constraintProfiles which contains a struct of defined fields:

this.constraintProfiles = {
	new = "fname,lname,email,password",
	update = "fname,lname,email",
	passUpdate = "password,confirmpassword"
}

Each key is the name of the profile like new, update passUpdate. The value of the profile is a list of fields to validate within that selected profile. In order to use it, just pass in one or more profile names into the validate() or validateOrFail() methods.

var results = validateModel( target=model, profiles="update" )
var results = validateModel( target=model, profiles="update,passUpdate" )
********************************************************************************
Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp
www.coldbox.org | www.luismajano.com | www.ortussolutions.com
********************************************************************************

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, its not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God. And not only so, but we glory in tribulations also: knowing that tribulation worketh patience; And patience, experience; and experience, hope: And hope maketh not ashamed; because the love of God is shed abroad in our hearts by the Holy Ghost which is given unto us. ." Romans 5:5

THE DAILY BREAD

"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.


Unreleased

4.4.0 - 2023-10-16

Added

  • requiredIf accepts a UDF and closure now

Fixed

  • UDF validator now treats nulls correctly

4.3.1 - 2023-06-15

Fixed

  • Only perform type evaluation if target value is not null or empty string #75

4.3.0 - 2023-05-05

4.2.0 - 2023-04-14

Added

  • New github action versions and consolidation of actions
  • New Contributing guidelines
  • New github support templates

Changed

  • The way custom validators are retrieved so they are ColdBox 7+ compatible
  • pr github action now just does format checks to avoid issues with other repos.
  • Consolidated Adobe 2021 scripts into the server scripts

Fixed

  • Fix for tasks.json file to include no recursion
  • #71 - ValidationManager errors when returning validatedKeys due to sharedconstraint name
  • #45 - Type validator needs to be able to validate against any type even if that is an empty string

[4.1.0] => 2022-NOV-14

Added

  • New ColdBox 7 delegate: Validatable@cbValidation which can be used to make objects validatable
  • New validators: notSameAs, notSameAsNoCase

Changed

  • All date comparison validators now validate as false when the comparison target dates values are NOT dates instead of throwing an exception.

[4.0.0] => 2022-OCT-10

Added

Fixed

Changed

  • Dropped ACF2016

[3.4.0] => 2022-JUN-27

Added

[3.3.0] => 2022-JAN-12

Added

Fixed

[3.2.0] => 2021-NOV-12

Added

  • Migrations to github actions
  • ACF2021 Support and automated testing

Fixed

  • Binary Type validator was not working by @nockhigan

Changed

[3.1.1] => 2021-MAY-17

Fixed

  • Regression when doing global replacements for validationData. It was changed to a !isStruct() but in reality, it has to be simple ONLY for replacements.

[3.1.0] => 2021-MAY-15

Added

  • New validator: DateEquals which can help you validate that a target value is a date and is the same date as the validation date or other field
  • New validator: After which can help you validate that a target value is a date and is after the validation date
  • New validator: AfterOrEqual which can help you validate that a target value is a date and is after or equal the validation date
  • New validator: Before which can help you validate that a target value is a date and is before the validation date
  • New validator: BeforeOrEqual which can help you validate that a target value is a date and is before or equal the validation date
  • New onError( closure ), onSuccess( closure ) callbacks that can be used to validate results using the validate() method and concatenate the callbacks.
  • New assert() helper that can assit you in validating truthful expressions or throwing exceptions
  • Two new helpers: validateIsNullorEmpty() and validateHasValue so you can do simple validations not only on objects and constraints.
  • RequiredIf, RequiredUnless can now be declared with a simple value pointing to a field. Basically testing if anotherField exists, or unless anotherField exists.
  • New BaseValidator for usage by all validators to bring uniformity, global di, and helpers.

Changed

  • The IValidator removes the getName() since that comes from the BaseValidator now.
  • The UniqueValidator now supports both creationg and update checks with new constraints.
  • Removed hard interface requirements to avoid lots of issues across CFML engines. Moved them to the interfaces folder so we can continue to document them and use them without direct compilation.

Fixed

  • Metadata for arguments did not have the right spacing for tosn of validators.
  • Added the missing rules struct argument to several validators that missed it.

[3.0.0] => 2021-JAN-20

Added

[2.3.0] => 2020-NOV-09

Added

  • New github latest changelog publish
  • Quote all memento keys so they can preserve their casing
  • Quote all metadata keys so they can preserve their casing

Fixed

  • Metadata for validations so the docs can be generated correctly

[2.2.0] => 2020-JUN-02

Added

  • New formatting rules
  • New automation standards
  • Automatic github publishing

Fixed

  • Deleted rogue UDFValidator embedded in the validators path
  • fix for BOX-63 and BOX-68 9393c30 wpdebruin [email protected] validationData cannot be converted to a string for UDF,RequiredUnless,RequiredIf,Unique so they are excluded from this message replacement

[2.1.0] => 2020-FEB-04

Added

  • feature : Added constraintProfiles to allow you to define which fields to validate according to defined profiles: https://github.com/coldbox-modules/cbvalidation/issues/37
  • feature : Updated RequiredUnless and RequiredIf to use struct literal notation instead of the weird parsing we did.
  • feature : Added the Unique validator thanks to @elpete!
  • feature : All validators now accept a rules argument, which is the struct of constraints for the specific field it's validating on
  • improvement : Added null support for the RequiredIf,RequiredUnless validator values

2.0.0 => 2020-JAN-31

Features

  • No more manual discovery of validators, automated registration and lookup process, cleaned lots of code on this one!
  • New Validator: Accepted - The field under validation must be yes, on, 1, or true. This is useful for validating "Terms of Service" acceptance.
  • New Validator: Alpha - Only allows alphabetic characters
  • New Validator: RequiredUnless with validation data as a struct literal { anotherField:value, ... } - The field under validation must be present and not empty unless the anotherfield field is equal to the passed value.
  • New Validator: RequiredIf with validation data as a struct literal { anotherField:value, ... } - The field under validation must be present and not empty if the anotherfield field is equal to the passed value.
  • Accelerated validation by removing type checks. ACF chokes on interface checks

Improvements

  • Consistency on all validators to ignore null or empty values except the Required validator
  • Formatting consistencies
  • Improve error messages to describe better validation
  • Get away from evaluate() instead use invoke()

Compat & Bugs

  • Bugs : Fixed lots of wrong type exceptions
  • Compat : Remove ACF11 support

[1.5.2]

  • bug : Added float to the type validator which was missing

[1.5.1]

  • bug : This version's mixin is causing errors because its looking for this.validate() and its looking in the handler, not in the mixin file itself.

[1.5.0]

  • features : validateOrFail() new method to validate and if it fails it will throw a ValidationException. Also if the target is an object, the object is returned. If the target is a struct, the struct is returned ONLY with the validated fields.
  • feature : validateModel() is now deprecated in favor of validate(). validateModel() is now marked for deprecation.
  • improvement : Direct scoping for performance an avoidance of lookup bugs
  • improvement : HTTPS protocol for everything
  • improvement : Updated to testbox 3
  • bug : Fix mapping declaration for apidocs`
  • bug : Missing return on addSharedConstraint() function

[1.4.1]

  • Location protocol

[1.4.0]

  • Updated to new layout
  • UDFValidator added rejectedValue to newError arguments: https://github.com/coldbox-modules/cbvalidation/pull/29/files
  • Removed lucee 4.5 support
  • Mixins missing comma on arguments
  • Switching evaluate to invoke for security and performance
  • Fix for passing arguments in newError() on the validation result object

[1.3.0]

  • Build updates and travis updates
  • Unified Workbench
  • MaxValidator The Max validator needs to better reflect that it can be less than or equal to the number to compare to <=
  • MinValidator The explanation needs to better reflect the min validator which is >=
  • Allow custom validators to be specified just by key and the payload to be passed in as validation data
  • GenericObject Should return null on non-existent keys instead of an exception if not we cannot validate nullness
  • You can now pass a list of fields to ONLY validate via validate() methods using the includeFields argument.

[1.2.1]

  • Dependency updates

[1.2.0]

  • Updated cbi18n dependency to latest
  • Travis updates
  • Type validator not countaing against 0 length values
  • Size validator typos
  • Migration to new github organization

[1.1.0]

  • Updated cbi18n dependency to version 1.2.0
  • SizeValidator not evaluating correctly non-required fields
  • Travis integration
  • Build script updates
  • Added array validation thanks to Sana Ullah

[1.0.3]

  • Exception on Lucee/Railo reporting wrong interface types when using imports
  • Exception message was wrong on UDFValidator
  • Ignore invalid validator keys, to allow for extra metadata and custom messages

[1.0.2]

  • production ignore lists
  • Unloading of helpers

[1.0.1]

[1.0.0]

  • Create first module version

$ box install cbvalidation

No collaborators yet.
   
5.00 / 1
  • {{ getFullDate("2014-05-03T12:34:42Z") }}
  • {{ getFullDate("2023-10-16T08:44:50Z") }}
  • 20,813
  • 675,177