Download the PHP package molajo/fieldhandler without Composer

======= Molajo Fieldhandler [Alpha]

Molajo Fieldhandler is an integrated data integrity assurance package for PHP applications. The approach validation and sanitation functionality very specifically as specialised tools. In unifying tool usage around a focus on field-level rule compliance, applications ensure data collection processes provide clean, verified, and useful information.

Mission critical applications rely on well designed and carefully implemented cleansing, formatting and verification routines. The goal of the Molajo Fieldhandler is to make it easier for PHP developers not only to accomplish this goal but as importantly to be able to communicate exactly how the application enforcing integrity constraints in terms that the client can understand.

Overview of the Methodology

At the most basic level, constraints define data collection and usage rules by describing qualities of the data. These rules might include specifications about the minimum and maximum values, number of occurrences for an array, whether or not a field is required or if there is a list or data range that can be used to confirm data values.

A critical step in application development associates specific integrity constraints with each field in the collection. It is simply not possible to ensure clean data if the rules defining that state are not articulated.

Define Integrity Constraints

As an example, assume these constraints for the password field:

1. Passwords can contain alphanumeric characters, the underscore (_), dollar sign ($), and pound sign (#).
2. Passwords must be from 8 to 30 characters in length.
3. Passwords expire every 90 days.
4. The new password cannot match the existing value.
5. Passwords should never be displayed and must be masked as asterisks.

Design enforcement strategy

Review the existing Molajo Fieldhandler Constraint classes to define enforcement. Custom Constraints can be created when delivered constraints are not enough.

1. Validate the password 'last change date' using the Date Constraint to verify the date is not over 90 days previous.
2. Validate the field data using the Alphanumeric Constraint and values (_), ($), and (#).
3. Validate the field data using the Length Constraint to ensure a length of 8 to 30 characters.
4. Escape the password using the Password Constraint class to replace password values with asterisks.

Write code to deploy enforcement strategy

Example: Verbose

This is a verbose example for purposes of learning where each constraint is specifically enforced.

Example: Field Collection

While the previous example showed how to perform each test, one at a time, it is also possible to group constraints for each field:

Example: Data Collection

If you define which fields belong to a data collection and what constraints apply to each field, Molajo Fieldhandler can manage constraint verification quite simply, as this example shows.

Creating Custom Constraints

INCOMPLETE

Messages

INCOMPLETE

Package Constraints

The examples in this section assume the Fieldhandler has been instantiated, as follows:

Alias

Each character in the alias URL slug must be alphanumeric or a dash.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Converts the value to a usable URL slug. In this example, $field_value will contain jack-and-jill.

Format

For alias, the format method produces the same results as sanitize.

Alpha

Each character in the alias URL slug must be alphabetic. To allow the 'space character', use the allow_space_character $option.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will contain Pat Nelson.

Format

For this constraint, the format method is not implemented. The value sent in is not evaluated or changed.

Alphanumeric

Each character in the alias URL slug must be a character or a digit. To allow the 'space character', use the allow_space_character $option.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will contain 4 dogs and 3 cats.

Format

For this constraint, the format method is not implemented. The value sent in is not evaluated or changed.

Arrays

Must be an array. Optionally, if $options['valid_values_array'] is provided, array values must match a value in the valid array. Optionally, if $options['array_minimum'] is specified, array entries must not be less than that value. Optionally, if $options['array_maximum'] is specified, array entries must not be exceed that value.

Validate

Verifies value (or array of values) against constraint, returning a TRUE or FALSE result and error messages

In this example, $response->getValidateResponse() is TRUE since b and c are in the valid array of a, b, c and because there are two entries in the input array which is more than the minimum value allowed of 1.

Sanitize

Returns null if the array does not meet the constraint definition.

In this example, $field_value is NULL since b and c are not in the valid array values.

Format

Not implemented. Value sent in is returned unchanged.

Boolean

Character must be true or false or NULL. (Use Default and/or Required if NULL is not allowed.)

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Sanitizes for true or false, else returns NULL.

Format

Not implemented. Value sent in is not evaluated or changed.

Callback

Enables use of a custom callable function or method to sanitize, filter and format data.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

In this example, the data value 'hello' is input to the callback 'strtoupper' and the result 'HELLO' is compared to the original value. Since the values are different, false is returned.

Sanitize

Executes the callable against the data value to produce a sanitized result.

In this example, $field_value will result in HELLO.

Format

For callback, the format method produces the same results as sanitize. It can be used to format data, as needed.

Contains

Within the string, a specified value exists.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

In this example, the response is false since the string does not contain the value specified.

Sanitize

Sets field to null if the value specified does not exist in the string.

In this example, the $field_value is NULL.

Format

For this constraint, the format method is not implemented. The value sent in is not evaluated or changed.

Controlcharacters

Each character must be a control character (ex. line feed, tab, escape). To allow the 'space character', use the allow_space_character $option.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will contain \n \r \t.

Format

For this constraint, the format method is not implemented. The value sent in is not evaluated or changed.

Date

Must be a valid formatted date.

Validate

Verifies the date according to the format defined in $options['create_from_format'], returning true if valid or false and error messages if not valid.

Sanitize

Validates the date and returns null for $field_value if the date does not conform to the constraint.

Format

Formats a date according to the format defined in $options['display_as_format'];

Defaults

Applies default value for sanitize and verifies if the value requires a default for validate.

Validate

Verifies if the value is null, if so, returns a FALSE that a default has not been applied. If the field has a value, validate returns TRUE.

Sanitize

Applies the default value defined in the $options array to the value, if the value is NULL.

Format

Not implemented. Value sent in is not evaluated or changed.

Digit

Each character must be a numeric digit. To allow the 'space character', use the allow_space_character $option.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will contain 1 2 3 4 5.

Format

For this constraint, the format method is not implemented. The value sent in is not evaluated or changed.

Email

Only letters, digits and !#$%&'*+-/=?^_{|}~@.[]`

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

This example returns true.

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will result in NULL.

Format

Format returns an obfuscated email address.

Encoded

URL-encode string, optionally strip or encode special characters.

The following flags can be applied by adding to the options array (see examples):

• FILTER_FLAG_STRIP_LOW
• FILTER_FLAG_STRIP_HIGH
• FILTER_FLAG_ENCODE_LOW
• FILTER_FLAG_ENCODE_HIGH

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages. For Encoded, the original value is compared to a sanitized value. If those values match, true is returned. Otherwise, the response is false and an error message is available.

Sanitize

Removes characters not conforming to the definition of the constraint.

In this example, the input URL is something.php?text=unknown values here. The resulting value is unknown%20values%20here.

Format

Format is not implemented for this constraint.

Equal

Tests that a value is equal to a specified value.

False

Value must conform to one of the values defined within the $valid_values_array.

To override, send in an options entry of the values desired:

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Returns null if value is not defined within the $valid_values_array.

Format

Not implemented. Value sent in is returned unchanged.

Fileextension

Value must conform to one of the values defined within the $valid_values_array.

To override, send in an options entry of the values desired:

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Returns null if value is not defined within the $valid_values_array.

Format

Not implemented. Value sent in is returned unchanged.

Float

Remove all characters except digits, +- and optionally .,eE.

Can be used with the following flags by defining $option entries for each flag desired:

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

This example returns true.

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will result in NULL.

Format

For this constraint, the format method is not implemented. The value sent in is not evaluated or changed.

Foreignkey

Uses the database connection defined in $options['database'] to execute a query that verifies there is a row for the table named in $options['table'] with a field named $options['key'] with a value of $field_value.

Fromto

Verifies that the $field_value is greater than the From value and less than the To value.

Fullspecialchars

Convert special characters to HTML entities:

'&' (ampersand) becomes '&' '"' (double quote) becomes '"' when ENT_NOQUOTES is not set. "'" (single quote) becomes ''' (or ') only when ENT_QUOTES is set. '<' (less than) becomes '<' '>' (greater than) becomes '>'

Encoding quotes can be disabled by:

Validate

Not implemented. Will always return false.

Sanitize

Convert special characters to HTML entities:

Format

Not implemented. The value sent in is returned unchanged.

Graph

Each character must be a visible, printable character. To allow the 'space character', use the allow_space_character $option.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will contain This is visible..

Format

For this constraint, the format method is not implemented. The value sent in is not evaluated or changed.

Hexidecimal

Each character must be a numeric digit. To allow the 'space character', use the allow_space_character $option.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will contain 1 2 3 4 5.

Format

For this constraint, the format method is not implemented. The value sent in is not evaluated or changed.

Html

add whitelist description Escapes HTML entities. Equivalent to htmlspecialchars with with ENT_QUOTES set.

Image

Tests that the value is an image.

Integer

Includes only digits, plus and minus sign.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

This example returns true.

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will result in NULL.

Format

Not implemented, simply returns the value sent in.

Ip

Tests that the value is an IP Address.

Lower

Each character must be an lowercase character. To allow the 'space character', use the allow_space_character $option.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

This example returns false due to the inclusion of non lowercase characters.

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will only contain the lowercase letter his is lower since the T and . are not lowercase.

Format

Lowercase all character values. In this example, $field_value will contain this is lower..

Maximum

Validates or filters/escapes numeric value to not exceed the maximum.

Mimetypes

Value must conform to one of the values defined within the $valid_values_array.

To override, send in an options entry of the values desired:

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Returns null if value is not defined within the $valid_values_array.

Format

Not implemented. Value sent in is returned unchanged.

Minimum

Validates or filters/escapes numeric value to not exceed the maximum.

Notequal

Tests that a value is not equal to a specified value.

Notnull

Value must not be a null value.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Not useful. (Can only return a NULL value if it is NULL.)

Format

Not implemented. Value sent in is returned unchanged.

Format

Not implemented. Value sent in is returned unchanged.

Nothing

Value must conform to one of the values defined within the $valid_values_array.

To override, send in an options entry of the values desired:

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Returns null if value is not defined within the $valid_values_array.

Format

Not implemented. Value sent in is returned unchanged.

Null

Value must be null.

Validate

Verifies that value is NULL.

Sanitize

Returns null if value is not not null. =)

Format

Not implemented. Value sent in is returned unchanged.

Numeric

Characters must be numeric.

Validate

Verifies if the value is numeric.

Sanitize

Returns null if value is not numeric.

Format

Not implemented. Value sent in is not evaluated or changed.

Object

Must be an object.

Validate

Verifies if the value is an object.

Sanitize

Returns null if value is not an object.

Format

Not implemented. Value sent in is not evaluated or changed.

Raw

Do nothing, optionally strip or encode special characters. FILTER_FLAG_STRIP_LOW, FILTER_FLAG_STRIP_HIGH, FILTER_FLAG_ENCODE_LOW, FILTER_FLAG_ENCODE_HIGH, FILTER_FLAG_ENCODE_AMP. See sanitize filters.

Printable

Each character must be a printable character.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

This example returns false due to the inclusion of control characters which cannot be displayed.

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will contain asdf.

Format

For this constraint, the format method is not implemented. The value sent in is not evaluated or changed.

Punctuation Constraint

Each character must be a punctuation character. To allow the 'space character', use the allow_space_character $option.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will contain * & $ ( ).

Format

For this constraint, the format method is not implemented. The value sent in is not evaluated or changed.

Regex

Performs regex checking against the input value for the regex sent in.

Required

Value must not be a null value.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Not useful. (Can only return a NULL value if it is NULL.)

Format

Not implemented. Value sent in is returned unchanged.

Format

Not implemented. Value sent in is returned unchanged.

Something

Value must not be one of the values defined within the $valid_values_array.

To override, send in an options entry of the values desired:

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Returns null if value is defined within the $valid_values_array.

String

Tests that the value is a string.

Stringlength

Tests that the length of the string is from a specific value and to a second value. From and To testing includes the from and to values.

Space Constraint

Each character must be a whitespace character. Besides the blank character this also includes tab, vertical tab, line feed, carriage return and form feed characters.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will contain \n \r \t.

Format

For this constraint, the format method is not implemented. The value sent in is not evaluated or changed.

Tel

Tests that the value is a string.

Time

Must be a valid formatted time.

Valitime

Verifies the time according to the format defined in $options['create_from_time_format'], returning true if valid or false and error messages if not valid.

Sanitize

Validate the time and returns null for $field_value if the time does not conform to the constraint.

Format

Formats a time according to the format defined in $options['display_as_time_format'];

Trim

The text must not have spaces before or after the last visible character.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

This example returns false due to the inclusion of spaces before and after the text string.

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will result in 'This is trimmed.' and the spaces preceding and following the text literal will be removed.

Format

Performs sanitize.

True

Value must conform to one of the values defined within the $valid_values_array.

To override, send in an options entry of the values desired:

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

Sanitize

Returns null if value is not defined within the $valid_values_array.

Format

Not implemented. Value sent in is returned unchanged.

Upper

Each character must be an lowercase character. To allow the 'space character', use the allow_space_character $option.

Validate

Verifies value against constraint, returning a TRUE or FALSE result and error messages

This example returns false due to the inclusion of non uppercase characters.

Sanitize

Removes characters not conforming to the definition of the constraint. In this example, $field_value will only contain the uppercase letter T since no other characters meet the constraint definition.

Format

Uppercase all character values. In this example, $field_value will contain THIS IS UPPER..

Url

Tests that a value is a valid email address. When invalid, validate throws exception while Filter and Escape return null.

Values

Value (or array of values) must be defined within the $options['valid_values_array'] array.

Validate

Verifies value (or array of values) against constraint, returning a TRUE or FALSE result and error messages

In this example, $response->getValidateResponse() is TRUE since a is in the array a, b, c.

Sanitize

Returns null if value (or array of values) is not defined within the $options['valid_values_array'].

In this example, $field_value is NULL since z is not a, b or c.

Format

Not implemented. Value sent in is returned unchanged.

Requirements and Compliance

• PHP framework independent, no dependencies
• Requires PHP 5.4, or above
• Semantic Versioning
• Compliant with:
  • PSR-1 Basic Coding Standards
  • PSR-2 Coding Style
  • PSR-4 Autoloader
• [phpDocumentor2] (https://github.com/phpDocumentor/phpDocumentor2)
• [phpUnit Testing] (https://github.com/sebastianbergmann/phpunit)
• Author AmyStephen
• [Travis Continuous Improvement] (https://travis-ci.org/profile/Molajo)
• Scrutinizer Analysis Testing using PHP Analyzer, PHP Mess Detector, PHP Code Sniffer, SensioLabs Security Advisory Checker, PHP PDepend, External Code Coverage, PHP Similarity Analyzer
• Listed on [Packagist] (http://packagist.org) and installed using [Composer] (http://getcomposer.org/)
• Use github to submit pull requests and features
• Licensed under the MIT License - see the LICENSE file for details