{"id":28839475,"url":"https://github.com/coldbox-modules/cbvalidation","last_synced_at":"2026-02-01T02:31:37.843Z","repository":{"id":16633555,"uuid":"19388719","full_name":"coldbox-modules/cbvalidation","owner":"coldbox-modules","description":"This module provides server side validation to ColdBox applications","archived":false,"fork":false,"pushed_at":"2026-01-01T18:15:56.000Z","size":1451,"stargazers_count":14,"open_issues_count":8,"forks_count":24,"subscribers_count":7,"default_branch":"development","last_synced_at":"2026-01-14T17:38:38.969Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":null,"language":"ColdFusion","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coldbox-modules.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.YML","license":null,"code_of_conduct":".github/CODE_OF_CONDUCT.MD","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"patreon":"ortussolutions"}},"created_at":"2014-05-02T21:10:44.000Z","updated_at":"2025-10-17T14:20:58.000Z","dependencies_parsed_at":"2025-02-19T13:27:18.136Z","dependency_job_id":"bc459ad6-cb5a-4f45-90bb-4e273b69762b","html_url":"https://github.com/coldbox-modules/cbvalidation","commit_stats":null,"previous_names":["coldbox/cbox-validation"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/coldbox-modules/cbvalidation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coldbox-modules%2Fcbvalidation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coldbox-modules%2Fcbvalidation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coldbox-modules%2Fcbvalidation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coldbox-modules%2Fcbvalidation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coldbox-modules","download_url":"https://codeload.github.com/coldbox-modules/cbvalidation/tar.gz/refs/heads/development","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coldbox-modules%2Fcbvalidation/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28965350,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T02:14:24.993Z","status":"ssl_error","status_checked_at":"2026-02-01T02:13:55.706Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2025-06-19T14:41:26.941Z","updated_at":"2026-02-01T02:31:37.838Z","avatar_url":"https://github.com/coldbox-modules.png","language":"ColdFusion","funding_links":["https://patreon.com/ortussolutions"],"categories":[],"sub_categories":[],"readme":"[![Total Downloads](https://forgebox.io/api/v1/entry/cbvalidation/badges/downloads)](https://forgebox.io/view/cbvalidation)\n[![Latest Stable Version](https://forgebox.io/api/v1/entry/cbvalidation/badges/version)](https://forgebox.io/view/cbvalidation)\n[![Apache2 License](https://img.shields.io/badge/License-Apache2-blue.svg)](https://forgebox.io/view/cbvalidation)\n\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"https://www.ortussolutions.com/__media/coldbox-185-logo.png\" alt=\"ColdBox Platform Logo\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\tCopyright Since 2005 ColdBox Platform by Luis Majano and Ortus Solutions, Corp\n\t\u003cbr\u003e\n\t\u003ca href=\"https://www.coldbox.org\"\u003ewww.coldbox.org\u003c/a\u003e |\n\t\u003ca href=\"https://www.ortussolutions.com\"\u003ewww.ortussolutions.com\u003c/a\u003e\n\u003c/p\u003e\n\n# Welcome to the Validation Module for ColdBox\n\nThis 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.  You can validate objects or structures and even use profiles to target specific fields for validation.  The validation engine is highly extensible and can be used in any kind of application.\n\nThe module leverages the power of the cbi18n module for internationalization support, providing localized validation messages, and integrates seamlessly with ColdBox's WireBox dependency injection container for maximum flexibility and testability.\n\n## License\n\nApache License, Version 2.0.\n\n## Important Links\n\n- https://github.com/coldbox-modules/cbvalidation\n- https://coldbox-validation.ortusbooks.com\n- https://forgebox.io/view/cbvalidation\n\n## Requirements\n\n- **BoxLang** 1.0+ (Preferred)\n- **Lucee** 5.x+\n- **Adobe ColdFusion** 2023+\n- **Dependencies**: ColdBox 7+, cbi18n 3.0+\n\n## Installation\n\nLeverage CommandBox to install:\n\n```bash\nbox install cbvalidation\n```\n\nThe 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()`\n\n## Documentation\n\nThis module is fully documented at: https://coldbox-validation.ortusbooks.com/. It also has an MCP server with live docs and examples.\n\n## WireBox Registrations\n\n- `ValidationManager@cbvalidation` - The core validation engine\n- `validationManager@cbvalidation` - Alias for convenience\n- Global validation helper methods injected into all ColdBox components\n\n## Mixins\n\nThe module will also register several methods in your handlers/interceptors/layouts/views\n\n```js\n/**\n * Validate an object or structure according to the constraints rules.\n *\n * @target An object or structure to validate\n * @fields The fields to validate on the target. By default, it validates on all fields\n * @constraints A structure of constraint rules or the name of the shared constraint rules to use for validation\n * @locale The i18n locale to use for validation messages\n * @excludeFields The fields to exclude from the validation\n * @includeFields The fields to include in the validation\n * @profiles If passed, a list of profile names to use for validation constraints\n *\n * @return cbvalidation.model.result.IValidationResult\n */\nfunction validate()\n\n/**\n * Validate an object or structure according to the constraints rules and throw an exception if the validation fails.\n * The validation errors will be contained in the `extendedInfo` of the exception in JSON format\n *\n * @target An object or structure to validate\n * @fields The fields to validate on the target. By default, it validates on all fields\n * @constraints A structure of constraint rules or the name of the shared constraint rules to use for validation\n * @locale The i18n locale to use for validation messages\n * @excludeFields The fields to exclude from the validation\n * @includeFields The fields to include in the validation\n * @profiles If passed, a list of profile names to use for validation constraints\n *\n * @return The validated object or the structure fields that where validated\n * @throws ValidationException\n */\nfunction validateOrFail()\n\n/**\n * Retrieve the application's configured Validation Manager\n */\nfunction getValidationManager()\n\n/**\n * Verify if the target value has a value\n * Checks for nullness or for length if it's a simple value, array, query, struct or object.\n */\nboolean function validateHasValue( any targetValue )\n\n/**\n * Check if a value is null or is a simple value and it's empty\n *\n * @targetValue the value to check for nullness/emptyness\n */\nboolean function validateIsNullOrEmpty( any targetValue )\n\n/**\n * This method mimics the Java assert() function, where it evaluates the target to a boolean value and it must be true\n * to pass and return a true to you, or throw an `AssertException`\n *\n * @target The tareget to evaluate for being true\n * @message The message to send in the exception\n *\n * @throws AssertException if the target is a false or null value\n * @return True, if the target is a non-null value. If false, then it will throw the `AssertError` exception\n */\nboolean function assert( target, message=\"\" )\n```\n\n## Settings\n\nHere are the module settings you can place in your `ColdBox.cfc` by using the `cbvalidation` settings structure in the `modulesettings`\n\n```js\nmodulesettings = {\n\tcbvalidation = {\n\t\t// The third-party validation manager to use, by default it uses CBValidation.\n\t\tmanager = \"class path\",\n\n\t\t// You can store global constraint rules here with unique names\n\t\tsharedConstraints = {\n\t\t\tuserRegistration = {\n\t\t\t\temail = { required=true, type=\"email\" },\n\t\t\t\tpassword = { required=true, size=\"8..50\" },\n\t\t\t\tfirstName = { required=true, size=\"1..50\" },\n\t\t\t\tlastName = { required=true, size=\"1..50\" }\n\t\t\t},\n\t\t\tuserUpdate = {\n\t\t\t\temail = { required=true, type=\"email\" },\n\t\t\t\tfirstName = { required=true, size=\"1..50\" },\n\t\t\t\tlastName = { required=true, size=\"1..50\" }\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\nYou can read more about ColdBox Validation here: - https://coldbox-validation.ortusbooks.com/\n\n## Constraints\n\nPlease 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.\n\nEach 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:\n\n```js\nthis.constraints = {\n\n\tpropertyName = {\n        // The field under validation must be yes, on, 1, or true. This is useful for validating \"Terms of Service\" acceptance.\n        accepted : any value\n\n        // The field under validation must be a date after the set targetDate\n        after : targetDate\n\n        // The field under validation must be a date after or equal the set targetDate\n        afterOrEqual : targetDate\n\n        // The field must be alphanumeric ONLY\n        alpha : any value\n\n        // The field under validation is an array and all items must pass this validation as well\n        arrayItem : {\n            // All the constraints to validate the items with\n        }\n\n        // The field under validation must be a date before the set targetDate\n        before : targetDate\n\n        // The field under validation must be a date before or equal the set targetDate\n        beforeOrEqual : targetDate\n\n        // The field under validation must be a date that is equal the set targetDate\n        dateEquals : targetDate\n\n        // discrete math modifiers\n        discrete : (gt,gte,lt,lte,eq,neq):value\n\n        // value in list\n        inList : list\n\n        // max value\n        max : value\n\n        // Validation method to use in the target object must return boolean accept the incoming value and target object\n        method : methodName\n\n        // min value\n        min : value\n\n        // range is a range of values the property value should exist in\n        range : eg: 1..10 or 5..-5\n\n        // regex validation\n        regex : valid no case regex\n\n        // required field or not, includes null values\n        required : boolean [false]\n\n        // The field under validation must be present and not empty if the `anotherfield` field is equal to the passed `value`.\n        requiredIf : {\n            anotherfield:value, anotherfield:value\n        }\n\n        // The field under validation must be present and not empty unless the `anotherfield` field is equal to the passed\n        requiredUnless : {\n            anotherfield:value, anotherfield:value\n        }\n\n        // same as but with no case\n        sameAsNoCase : propertyName\n\n        // same as another property\n        sameAs : propertyName\n\n        // size or length of the value which can be a (struct,string,array,query)\n        size  : numeric or range, eg: 10 or 6..8\n\n        // specific type constraint, one in the list.\n        type  : (alpha,array,binary,boolean,component,creditcard,date,email,float,GUID,integer,ipaddress,json,numeric,query,ssn,string,struct,telephone,url,usdate,UUID,xml,zipcode),\n\n        // UDF to use for validation, must return boolean accept the incoming value and target object, validate(value,target):boolean\n        udf = variables.UDF or this.UDF or a closure.\n\n        // Check if a column is unique in the database\n        unique = {\n            table : The table name,\n            column : The column to check, defaults to the property field in check\n        }\n\n        // Custom validator, must implement coldbox.system.validation.validators.IValidator\n        validator : path or wirebox id, example: 'mypath.MyValidator' or 'id:MyValidator'\n\t}\n\n}\n```\n\n## Usage Examples\n\n### Basic Validation in Handlers\n\n```js\nfunction saveUser( event, rc, prc ){\n\tvar results = validate( target=rc, constraints=\"userRegistration\" );\n\tif( results.hasErrors() ){\n\t\tprc.errors = results.getAllErrors();\n\t\treturn event.setView( \"users/registration\" );\n\t}\n\t// Process valid data\n\tvar user = userService.create( rc );\n}\n```\n\n### Exception Based Validation\n\n```js\nfunction apiCreateUser( event, rc, prc ){\n\ttry{\n\t\tvar validData = validateOrFail( target=rc, profiles=\"registration\" );\n\t\tvar user = userService.create( validData );\n\t\treturn event.renderData( data=user );\n\t} catch( ValidationException e ){\n\t\treturn event.renderData(\n\t\t\tstatusCode=422,\n\t\t\tdata={ errors: deserializeJSON( e.extendedInfo ) }\n\t\t);\n\t}\n}\n```\n\n### Object-Based Constraints\n\n```js\nclass {\n\n\tthis.constraints = {\n\t\temail = { required=true, type=\"email\" },\n\t\tage = { required=true, min=18, max=65 },\n\t\tpassword = { required=true, size=\"8..50\" },\n\t\tconfirmPassword = { required=true, sameAs=\"password\" },\n\t\t\"address.street\" = { required=true, size=\"5..100\" },\n\t\t\"preferences.*\" = { type=\"string\" }\n\t};\n\n\tthis.constraintProfiles = {\n\t\tregistration = \"email,password,confirmPassword\",\n\t\tupdate = \"email,firstName,lastName\",\n\t\tpasswordChange = \"password,confirmPassword\"\n\t};\n\n}\n```\n\n## BoxLang CLI Runner\n\nRun your validation tests with the BoxLang CLI:\n\n```bash\n# Run all tests\nboxlang-cli test run\n\n# Run with specific runner\nboxlang-cli test run --runner=\"http://localhost:60299/tests/runner.cfm\"\n\n# Run specific test bundle\nboxlang-cli test run --bundles=\"test-harness/tests\"\n\n# Run with verbose output\nboxlang-cli test run --verbose\n```\n\n## Constraint Profiles\n\nYou 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:\n\n```js\nthis.constraintProfiles = {\n\tnew = \"fname,lname,email,password\",\n\tupdate = \"fname,lname,email\",\n\tpassUpdate = \"password,confirmpassword\"\n}\n```\n\nEach 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.\n\n```js\nvar results = validateModel( target=model, profiles=\"update\" )\nvar results = validateModel( target=model, profiles=\"update,passUpdate\" )\n```\n\n```\n********************************************************************************\nCopyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp\nwww.coldbox.org | www.luismajano.com | www.ortussolutions.com\n********************************************************************************\n```\n\n## HONOR GOES TO GOD ABOVE ALL\n\nBecause of His grace, this project exists. If you don't like this, then don't read it, its not for you.\n\n\u003e\"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ:\nBy whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God.\nAnd not only so, but we glory in tribulations also: knowing that tribulation worketh patience;\nAnd patience, experience; and experience, hope:\nAnd 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\n\n## THE DAILY BREAD\n\n \u003e \"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)\" Jn 14:1-12\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoldbox-modules%2Fcbvalidation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoldbox-modules%2Fcbvalidation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoldbox-modules%2Fcbvalidation/lists"}