FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...

ColdBox Validation

v2.3.0+143 Public

Build Status

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 2016+

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 [email protected]. 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()

Settings

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

validation = {
    // 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 must be alpahbetical ONLY
		alpha : any value,

		// 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  : (ssn,email,url,alpha,boolean,date,usdate,eurodate,numeric,GUID,UUID,integer,string,telephone,zipcode,ipaddress,creditcard,binary,component,query,struct,json,xml),

		// 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

Dependencies (1)


Dev Dependencies (0)


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.


[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.
   
  • {{ getFullDate("Nov 09 2020 04:11 PM GMT") }}
  • {{ getFullDate("Nov 09 2020 04:11 PM GMT") }}
  • 6,464
  • 5,867
  • 207,221