{ "content": [ { "type": "text", "text": "# Data::FormValidator::Constraints (perldoc)\n\n## NAME\n\nData::FormValidator::Constraints - Basic sets of constraints on input profile.\n\n## SYNOPSIS\n\nuse Data::FormValidator::Constraints qw(:closures);\nIn an Data::FormValidator profile:\nconstraintmethods => {\nemail => email(),\nphone => americanphone(),\nfirstnames => {\nconstraintmethod => FVmaxlength(3),\nname => 'mycustomname',\n},\n},\nmsgs => {\nconstraints => {\nmycustomname => 'My message',\n},\n},\n\n## DESCRIPTION\n\nThese are the builtin constraints that can be specified by name in the input profiles.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **RENAMING BUILT-IN CONSTAINTS**\n- **PROCEDURAL INTERFACE**\n- **WRITING YOUR OWN CONSTRAINT ROUTINES** (3 subsections)\n- **BACKWARDS COMPATIBILITY**\n- **SEE ALSO** (2 subsections)\n- **CREDITS**\n- **AUTHORS**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Data::FormValidator::Constraints", "section": "", "mode": "perldoc", "summary": "Data::FormValidator::Constraints - Basic sets of constraints on input profile.", "synopsis": "use Data::FormValidator::Constraints qw(:closures);\nIn an Data::FormValidator profile:\nconstraintmethods => {\nemail => email(),\nphone => americanphone(),\nfirstnames => {\nconstraintmethod => FVmaxlength(3),\nname => 'mycustomname',\n},\n},\nmsgs => {\nconstraints => {\nmycustomname => 'My message',\n},\n},", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 18, "subsections": [] }, { "name": "DESCRIPTION", "lines": 124, "subsections": [] }, { "name": "RENAMING BUILT-IN CONSTAINTS", "lines": 31, "subsections": [] }, { "name": "PROCEDURAL INTERFACE", "lines": 32, "subsections": [] }, { "name": "WRITING YOUR OWN CONSTRAINT ROUTINES", "lines": 1, "subsections": [ { "name": "New School Constraints Overview", "lines": 48 }, { "name": "Old School Constraints", "lines": 36 }, { "name": "Methods available for use inside of constraints", "lines": 84 } ] }, { "name": "BACKWARDS COMPATIBILITY", "lines": 22, "subsections": [] }, { "name": "SEE ALSO", "lines": 1, "subsections": [ { "name": "Constraints available in other modules", "lines": 10 }, { "name": "Related modules in this package", "lines": 8 } ] }, { "name": "CREDITS", "lines": 5, "subsections": [] }, { "name": "AUTHORS", "lines": 5, "subsections": [] }, { "name": "COPYRIGHT", "lines": 8, "subsections": [] } ], "sections": { "NAME": { "content": "Data::FormValidator::Constraints - Basic sets of constraints on input profile.\n", "subsections": [] }, "SYNOPSIS": { "content": "use Data::FormValidator::Constraints qw(:closures);\n\nIn an Data::FormValidator profile:\n\nconstraintmethods => {\nemail => email(),\nphone => americanphone(),\nfirstnames => {\nconstraintmethod => FVmaxlength(3),\nname => 'mycustomname',\n},\n},\nmsgs => {\nconstraints => {\nmycustomname => 'My message',\n},\n},\n", "subsections": [] }, "DESCRIPTION": { "content": "These are the builtin constraints that can be specified by name in the input profiles.\n\nBe sure to check out the SEE ALSO section for even more pre-packaged constraints you can use.\n\nFVlengthbetween(1,23)\nFVmaxlength(23)\nFVminlength(1)\nuse Data::FormValidator::Constraints qw(\nFVlengthbetween\nFVminlength\nFVmaxlength\n);\n\nconstraintmethods => {\n\n# specify a min and max, inclusive\nlastname => FVlengthbetween(1,23),\n\n}\n\nSpecify a length constraint for a field.\n\nThese constraints have a different naming convention because they are higher-order functions.\nThey take input and return a code reference to a standard constraint method. A constraint name\nof \"lengthbetween\", \"minlength\", or \"maxlength\" will be set, corresponding to the function\nname you choose.\n\nThe checks are all inclusive, so a max length of '100' will allow the length 100.\n\nLength is measured in perl characters as opposed to bytes or anything else.\n\nThis constraint *will* untaint your data if you have untainting turned on. However, a length\ncheck alone may not be enough to insure the safety of the data you are receiving. Using\nadditional constraints to check the data is encouraged.\n\nFVeqwith\nuse Data::FormValidator::Constraints qw( FVeqwith );\n\nconstraintmethods => {\npassword => FVeqwith('passwordconfirm'),\n}\n\nCompares the current field to another field. A constraint name of \"eqwith\" will be set.\n\nFVnumvalues\nuse Data::FormValidator::Constraints qw ( FVnumvalues );\n\nconstraintmethods => {\nattachments => FVnumvalues(4),\n}\n\nChecks the number of values in the array named by this param. Note that this is useful for\nmaking sure that only one value was passed for a given param (by supplying a size argument of\n1). A constraint name of \"numvalues\" will be set.\n\nFVnumvaluesbetween\nuse Data::FormValidator::Constraints qw ( FVnumvaluesbetween );\n\nconstraintmethods => {\nattachments => FVnumvaluesbetween(1,4),\n}\n\nChecks that the number of values in the array named by this param is between the supplied bounds\n(inclusively). A constraint name of \"numvaluesbetween\" will be set.\n\nemail\nChecks if the email LOOKS LIKE an email address. This should be sufficient 99% of the time.\n\nLook elsewhere if you want something super fancy that matches every possible variation that is\nvalid in the RFC, or runs out and checks some MX records.\n\nstateorprovince\nThis one checks if the input correspond to an american state or a canadian province.\n\nstate\nThis one checks if the input is a valid two letter abbreviation of an American state.\n\nprovince\nThis checks if the input is a two letter Canadian province abbreviation.\n\nziporpostcode\nThis constraints checks if the input is an American zipcode or a Canadian postal code.\n\npostcode\nThis constraints checks if the input is a valid Canadian postal code.\n\nzip\nThis input validator checks if the input is a valid american zipcode : 5 digits followed by an\noptional mailbox number.\n\nphone\nThis one checks if the input looks like a phone number, (if it contains at least 6 digits.)\n\namericanphone\nThis constraints checks if the number is a possible North American style of phone number : (XXX)\nXXX-XXXX. It has to contains 7 or more digits.\n\nccnumber\nThis constraint references the value of a credit card type field.\n\nconstraintmethods => {\nccno => ccnumber({fields => ['cctype']}),\n}\n\nThe number is checked only for plausibility, it checks if the number could be valid for a type\nof card by checking the checksum and looking at the number of digits and the number of digits of\nthe number.\n\nThis functions is only good at catching typos. IT DOESN'T CHECK IF THERE IS AN ACCOUNT\nASSOCIATED WITH THE NUMBER.\n\nccexp\nThis one checks if the input is in the format MM/YY or MM/YYYY and if the MM part is a valid\nmonth (1-12) and if that date is not in the past.\n\ncctype\nThis one checks if the input field starts by M(asterCard), V(isa), A(merican express) or\nD(iscovery).\n\nipaddress\nThis checks if the input is formatted like a dotted decimal IP address (v4). For other kinds of\nIP address method, See Regexp::Common::net which provides several more options. \"REGEXP::COMMON\nSUPPORT\" explains how we easily integrate with Regexp::Common.\n", "subsections": [] }, "RENAMING BUILT-IN CONSTAINTS": { "content": "If you'd like, you can rename any of the built-in constraints. Just define the constraintmethod\nand name in a hashref, like this:\n\nconstraintmethods => {\nfirstnames => {\nconstraintmethod => FVmaxlength(3),\nname => 'customlength',\n}\n},\n\nREGEXP::COMMON SUPPORT\nData::FormValidator also includes built-in support for using any of regular expressions in\nRegexp::Common as named constraints. Simply use the name of regular expression you want. This\nworks whether you want to untaint the data or not. For example:\n\nuse Data::FormValidator::Constraints qw(:regexpcommon);\n\nconstraintmethods => {\nmyipaddress => FVnetIPv4(),\n\n# An example with parameters\notherip => FVnetIPv4(-sep=>' '),\n}\n\nNotice that the routines are named with the prefix \"FV\" instead of \"RE\" now. This is simply a\nvisual cue that these are slightly modified versions. We've made a wrapper for each\nRegexp::Common routine so that it can be used as a named constraint like this.\n\nBe sure to check out the Regexp::Common syntax for how its syntax works. It will make more sense\nto add future regular expressions to Regexp::Common rather than to Data::FormValidator.\n", "subsections": [] }, "PROCEDURAL INTERFACE": { "content": "You may also call these functions directly through the procedural interface by either importing\nthem directly or importing the whole *:validators* group. This is useful if you want to use the\nbuilt-in validators out of the usual profile specification interface.\n\nFor example, if you want to access the *email* validator directly, you could either do:\n\nuse Data::FormValidator::Constraints (qw/validemail/);\nor\nuse Data::FormValidator::Constraints (:validators);\n\nif (validemail($email)) {\n# do something with the email address\n}\n\nNotice that when you call validators directly, you'll need to prefix the validator name with\n\"valid\"\n\nEach validator also has a version that returns the untainted value if the validation succeeded.\nYou may call these functions directly through the procedural interface by either importing them\ndirectly or importing the *:matchers* group. For example if you want to untaint a value with the\n*email* validator directly you may:\n\nif ($email = matchemail($email)) {\nsystem(\"echo $email\");\n}\nelse {\ndie \"Unable to validate email\";\n}\n\nNotice that when you call validators directly and want them to return an untainted value, you'll\nneed to prefix the validator name with \"match\"\n", "subsections": [] }, "WRITING YOUR OWN CONSTRAINT ROUTINES": { "content": "", "subsections": [ { "name": "New School Constraints Overview", "content": "This is the current recommended way to write constraints. See also \"Old School Constraints\".\n\nThe most flexible way to create constraints to use closures-- a normal seeming outer subroutine\nwhich returns a customized DFV method subroutine as a result. It's easy to do. These \"constraint\nmethods\" can be named whatever you like, and imported normally into the name space where the\nprofile is located.\n\nLet's look at an example.\n\n# Near your profile\n# Of course, you don't have to export/import if your constraints are in the same\n# package as the profile.\nuse My::Constraints 'coolness';\n\n# In your profile\nconstraintmethods => {\nemail => email(),\nprospectivedate => coolness( 40, 60,\n{fields => [qw/personality smarts goodlooks/]}\n),\n}\n\nLet's look at how this complex \"coolness\" constraint method works. The interface asks for users\nto define minimum and maximum coolness values, as well as declaring three data field names that\nwe should peek into to look their values.\n\nHere's what the code might look like:\n\nsub coolness {\nmy ($mincool,$maxcool, $attrs) = @;\nmy ($personality,$smarts,$looks) = @{ $attrs->{fields} } if $attrs->{fields};\nreturn sub {\nmy $dfv = shift;\n\n# Name it to refer to in the 'msgs' system.\n$dfv->namethis('coolness');\n\n# value of 'prospectivedate' parameter\nmy $val = $dfv->getcurrentconstraintvalue();\n\n# get other data to refer to\nmy $data = $dfv->getfiltereddata;\n\nmy $hasallthree = ($data->{$personality} && $data->{$smarts} && $data->{$looks});\nreturn ( ($val >= $mincool) && ($val <= $maxcool) && $hasallthree );\n}\n}\n" }, { "name": "Old School Constraints", "content": "Here is documentation on how old school constraints are created. These are supported, but the\nnew school style documented above is recommended.\n\nSee also the \"validatorpackages\" option in the input profile, for loading sets of old school\nconstraints from other packages.\n\nOld school constraint routines are named two ways. Some are named with the prefix \"match\" while\nothers start with \"valid\". The difference is that the \"match\" routines are built to untaint\nthe data and return a safe version of it if it validates, while \"valid\" routines simply return\na true value if the validation succeeds and false otherwise.\n\nIt is preferable to write \"match\" routines that untaint data for the extra security benefits.\nPlus, Data::FormValidator will AUTOLOAD a \"valid\" version if anyone tries to use it, so you\nonly need to write one routine to cover both cases.\n\nUsually constraint routines only need one input, the value being specified. However, sometimes\nmore than one value is needed.\n\nExample:\n\nimagefield => {\nconstraintmethod => 'maximagedimensions',\nparams => [\\100,\\200],\n},\n\nUsing that syntax, the first parameter that will be passed to the routine is the\nData::FormValidator object. The remaining parameters will come from the \"params\" array. Strings\nwill be replaced by the values of fields with the same names, and references will be passed\ndirectly.\n\nIn addition to \"constraintmethod\", there is also an even older technique using the name\n\"constraint\" instead. Routines that are designed to work with \"constraint\" *don't* have access\nto Data::FormValidator object, which means users need to pass in the name of the field being\nvalidated. Besides adding unnecessary syntax to the user interface, it won't work in conjunction\nwith \"constraintregexpmap\".\n" }, { "name": "Methods available for use inside of constraints", "content": "A few useful methods to use on the Data::FormValidator::Results object are available to you to\nuse inside of your routine.\n\ngetinputdata()\nReturns the raw input data. This may be a CGI object if that's what was used in the constraint\nroutine.\n\nExamples:\n\n# Raw and uncensored\nmy $data = $self->getinputdata;\n\n# tamed to be a hashref, if it wasn't already\nmy $data = $self->getinputdata( ashashref => 1 );\n\ngetfiltereddata()\nmy $data = $self->getfiltereddata;\n\nReturns the valid filtered data as a hashref, regardless of whether it started out as a CGI.pm\ncompatible object. Multiple values are expressed as array references.\n\ngetcurrentconstraintfield()\nReturns the name of the current field being tested in the constraint.\n\nExample:\n\nmy $field = $self->getcurrentconstraintfield;\n\nThis reduces the number of parameters that need to be passed into the routine and allows\nmulti-valued constraints to be used with \"constraintregexpmap\".\n\nFor complete examples of multi-valued constraints, see Data::FormValidator::Constraints::Upload\n\ngetcurrentconstraintvalue()\nReturns the name of the current value being tested in the constraint.\n\nExample:\n\nmy $value = $self->getcurrentconstraintvalue;\n\nThis reduces the number of parameters that need to be passed into the routine and allows\nmulti-valued constraints to be used with \"constraintregexpmap\".\n\ngetcurrentconstraintname()\nReturns the name of the current constraint being applied\n\nExample:\n\nmy $value = $self->getcurrentconstraintname;\n\nThis is useful for building a constraint on the fly based on its name. It's used internally as\npart of the interface to the Regexp::Commmon regular expressions.\n\nuntaintedconstraintvalue()\nreturn $dfv->untaintedconstraintvalue($match);\n\nIf you have written a constraint which untaints, use this method to return the untainted result.\nIt will prepare the right result whether the user has requested untainting or not.\n\nnamethis()\nsetcurrentconstraintname()\nSets the name of the current constraint being applied.\n\nExample:\n\nsub myconstraint {\nmy @outerparams = @;\nreturn sub {\nmy $dfv = shift;\n$dfv->setcurrentconstraintname('myconstraint');\nmy @params = @outerparams;\n# do something constraining here...\n}\n}\n\nBy returning a closure which uses this method, you can build an advanced named constraint in\nyour profile, before you actually have access to the DFV object that will be used later. See\nData::FormValidator::Constraints::Upload for an example.\n\n\"namethis\" is a provided as a shorter synonym.\n\nThe \"meta()\" method may also be useful to communicate meta data that may have been found. See\nData::FormValidator::Results for documentation of that method.\n" } ] }, "BACKWARDS COMPATIBILITY": { "content": "Prior to Data::FormValidator 4.00, constraints were specified a bit differently. This older\nstyle is still supported.\n\nIt was not necessary to explicitly load some constraints into your name space, and the names\nwere given as strings, like this:\n\nconstraints => {\nemail => 'email',\nfax => 'americanphone',\nphone => 'americanphone',\nstate => 'state',\nmyipaddress => 'REnetIPv4',\notherip => {\nconstraint => 'REnetIPv4',\nparams => [ \\'-sep'=> \\' ' ],\n},\nmyccno => {\nconstraint => 'ccnumber',\nparams => [qw/ccno cctype/],\n}\n},\n", "subsections": [] }, "SEE ALSO": { "content": "", "subsections": [ { "name": "Constraints available in other modules", "content": "Data::FormValidator::Constraints::Upload - validate the bytes, format and dimensions of file\nuploads\nData::FormValidator::Constraints::DateTime - A newer DateTime constraint module. May save you a\nstep of transforming the date into a more useful format after it's validated.\nData::FormValidator::Constraints::Dates - the original DFV date constraint module. Try the newer\none first!\nData::FormValidator::Constraints::Japanese - Japan-specific constraints\nData::FormValidator::Constraints::MethodsFactory - a useful collection of tools generate more\ncomplex constraints. Recommended!\n" }, { "name": "Related modules in this package", "content": "Data::FormValidator::Filters - transform data before constraints are applied\nData::FormValidator::ConstraintsFactory - This is a historical collection of constraints that\nsuffer from cumbersome names. They are worth reviewing though-- \"makeandconstraint\" will allow\none to validate against a list of constraints and shortcircuit if the first one fails. That's\nperfect if the second constraint depends on the first one having passed. For a modern version of\nthis toolkit, see Data::FormValidator::Constraints::MethodsFactory.\nData::FormValidator\n" } ] }, "CREDITS": { "content": "Some of those input validation functions have been taken from MiniVend by Michael J. Heins\n\nThe credit card checksum validation was taken from contribution by Bruce Albrecht to the\nMiniVend program.\n", "subsections": [] }, "AUTHORS": { "content": "Francis J. Lacoste\nMichael J. Heins\nBruce Albrecht\nMark Stosberg\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright (c) 1999 iNsu Innovations Inc. All rights reserved.\n\nParts Copyright 1996-1999 by Michael J. Heins Parts Copyright 1996-1999 by Bruce Albrecht Parts\nCopyright 2005-2009 by Mark Stosberg\n\nThis program is free software; you can redistribute it and/or modify it under the terms as perl\nitself.\n", "subsections": [] } } } }