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

ColdBox Validation

v2.1.0+126 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.

IMPORTANT LINKS

  • https://github.com/coldbox-modules/cbvalidation
  • https://coldbox-validation.ortusbooks.com
  • https://forgebox.io/view/cbvalidation

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
 *
 * @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
 *
 * @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'
	}

}
********************************************************************************
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

2.1.0

  • 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!
  • improvement : Added null support for the RequiredIf,RequiredUnless validator values

2.0.0

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

`requiredUnless=role,test

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

  • https://ortussolutions.atlassian.net/browse/CCM-21 Force the validation manager binder mapping
  • https://ortussolutions.atlassian.net/browse/CCM-20 ValidationManager missing singleton persistance

1.0.0

  • Create first module version

Here are all the versions for this package. Please note that you can leverage CommandBox package versioning to install any package you like. Please refer to our managing package version guide for more information.

Version Created Last Update Published By Stable Actions
Current
2.2.0-snapshot Feb 04 2020 11:45 AM Mar 06 2020 09:38 AM
Version History
2.1.0+126 Mar 11 2020 04:32 PM Mar 11 2020 04:32 PM
2.1.0+109 Feb 04 2020 11:44 AM Feb 04 2020 11:44 AM
2.1.0-snapshot Jan 31 2020 05:23 PM Jan 31 2020 05:23 PM
2.0.1+105 Feb 04 2020 09:53 AM Feb 04 2020 09:53 AM
2.0.1-snapshot Feb 03 2020 05:26 PM Feb 03 2020 05:26 PM
2.0.0+93 Jan 31 2020 05:23 PM Jan 31 2020 05:23 PM
2.0.0-snapshot Jan 31 2020 02:57 PM Jan 31 2020 02:57 PM
1.6.0-snapshot Aug 30 2019 12:35 PM Aug 30 2019 12:35 PM
1.5.2+87 Jan 23 2020 05:41 PM Jan 23 2020 05:41 PM
1.5.2-snapshot Jan 23 2020 05:22 PM Jan 23 2020 05:22 PM
1.5.1+78 Aug 30 2019 12:31 PM Aug 30 2019 12:31 PM
1.5.1-snapshot Aug 30 2019 12:31 PM Aug 30 2019 12:31 PM
1.5.0+76 Aug 30 2019 09:22 AM Aug 30 2019 09:22 AM
1.5.0-snapshot Mar 05 2019 02:34 PM Mar 06 2019 09:34 AM
1.4.1+69 Mar 06 2019 11:37 AM Mar 06 2019 11:37 AM
1.4.1-snapshot Mar 06 2019 11:32 AM Mar 06 2019 11:32 AM
1.4.0+63 Mar 05 2019 02:28 PM Mar 06 2019 06:54 AM
1.4.0+60 Mar 05 2019 10:58 AM Mar 06 2019 06:54 AM
1.4.0-snapshot Dec 04 2017 03:19 PM Mar 05 2019 02:21 PM
1.3.1+51 Dec 01 2017 02:17 PM Dec 01 2017 02:17 PM
1.3.1-snapshot Dec 01 2017 10:03 AM Dec 01 2017 10:03 AM
1.3.0+47 Nov 30 2017 04:44 PM Nov 30 2017 04:44 PM
1.3.0-snapshot Nov 30 2017 04:23 PM Nov 30 2017 04:23 PM
1.2.1+29 Nov 04 2016 12:14 PM Nov 04 2016 12:14 PM
1.2.0+24 Oct 09 2016 10:43 AM Oct 09 2016 10:43 AM
1.1.0 May 03 2014 12:34 PM Jun 10 2016 03:18 AM

 

$ box install cbvalidation

No collaborators yet.
   
  • May 03 2014 12:34 PM
  • Mar 11 2020 04:32 PM
  • 5,164
  • 4,492
  • 146,403