Download the PHP package forensic/handler without Composer

Handler

Forensic Handler is a php module that sits independently between the controller and the model, performing request data validation, serialization and integrity checks. It is easy to setup and independent of any php framework and ORMs.

It makes the validation process easy and requires you to just define the data validation rules which are just php arrays.

The most interesting part is how easy it is to validate array of field data and files and the wide range of validation rule types that it affords you. It is also extensible so that you can define more validation rules if the need be. See How to Write Your Custom Validation Types for instructions

Regarding database integrity checks, it is extensible enough to leave the db check implementation up to you by defining an abstract DBCheckerAbstract class. This makes it not tied to any framework or ORM. See How To Implement the DBCheckerAbstract Interface for instructions.

Getting Started

Install via composer:

Simple Usage Example

The Handler:

The Controller:

Note that processed data can be accessed directly on the instance, thanks to php's magic __get() method. However, it throws KeyNotFoundException if you try accessing data whose key is not defined to help in troubleshooting.

Validation Rule Formats

Validation rules are defined as arrays keyed by the field names. Each field array can contain the following rule properties:

1. type: This indicates the type of validation to carry out on the field.

2. required: Boolean value that indicates if the field is required. defaults to true.

3. default: This property applies to non required field. It defaults to null.

4. filters: Defines array of filters to apply to the field value(s) prior to validations.

5. check: Array containing a database integrity check to run on the field value(s)

6. checks: Contains array of multiple database integrity checks to run on the field value(s).

7. options: Array containing every other validation rules

8. requiredIf: A conditional clause that makes the field mandatory if the clause is satisfied.

To reference a validation principal, the convention used is to enclose the principal field name in curly braces within a string . '{field-name}'. The module will find and resolve such, replacing it with the field value.

Other conventions include {this} which references the current field value under validation; {_this} references the current field name under validation while {_index} references the current field value index position (in the case of validating array of fields).

Finally, there is the {CURRENT_DATE}, {CURRENT_YEAR}, {CURRENT_TIME} that references the current date, current year and current timestamp values respectively.

Validation Filters

Filters are applied to the field values prior to validations. You can use filters to modify field values prior to validation. The available filters include:

1. decode: Call php urldecode() function on the field value(s). Defaults to true

2. trim: Call php trim() function on the field value(s). Defaults to true

3. stripTags: Call php strip_tags() function on the field value(s). Defaults to true

4. stripTagsIgnore: Defines string of html tags that should not be stripped out if stripTags filter is set to true. defaults to empty string

5. numeric: Call php floatval() function on the field value(s). Defaults to false

6. toUpper: Call php strtoupper() function on the field value(s). Defaults to false

7. toLower: Call php strtolower() function on the field value(s). Defaults to false

Validation Rule Types

The module defines lots of validation rule types that covers a wide range of validation cases. These includes the following:

• Limiting Rule Validation

• Regex Rule Validation

• MatchWith Rule Validation

• Date Validation

• Range Validation

• Choice Validation

• Email Validation

• URL Validation

• Numeric Validation

• Password Validation

• File Validation

• Image File Validation

• Audio File Validation

• Video File Validation

• Media File Validation

• Document File Validation

• Archive File Validation

Limiting Rule Validation

The limiting rule validation options touches every validation. It is where we can define the limiting length of a string, date or numeric values. These includes the min, max, gt (greater than) and lt (less than) options.

Regex Rule Validation

It is quite easy to carry out different flavours of regex rule tests on field value(s). There are four kinds of regex rules. These include single regex test, regexAny, regexAll, and regexNone tests.

For regex type, it must match the test, otherwise it is flagged as error. For regexAny, at least one of the tests must match. For regexAll, all regex tests must match. For regexNone, none of the regex tests should match.

MatchWith Rule Validation

This rule is handy when you want to make sure that a field's value matches another field's value such as in password confirmation fields as well as email and phone confirmation scenerios.

Date Validation

To validate dates, set the type property to 'date'. You can specify limiting rules that validates if the date is within a given limited range.

Range Validation

To validate field as a range of value, set the type property to range. The range type accepts three more options keys, which are from, to and the optional step key that defaults to 1.

Choice Validation

To validate field against a choice of options, set the type property to choice. Acceptable options are specified using the choices property as array. The range type makes use of this type validator internally.

Email Validation

To validate email addresses, set the type property to email.

URL Validation

To validate url, set the type property to url.

Numeric Validation

To validate numeric values, whether floating or integers, there are nice validation types defined for such cases. These include the following types: float (money or number), positiveFloat or pFloat, negativeFloat or nFloat, integer or int, positiveInteger (positiveInt, pInteger or pInt), and negativeInteger (negativeInt, nInteger or nInt)

Password Validation

Password type validation is more like text validation except that some limiting rules and regex rules were added. The default validation implementation is that passwords must be at least 8 charaters long, and 28 characters max. It must contain at least two alphabets and at least two non-alphabets. You can override this default if you like.

File Validation

The module can validate files, including the integrity of file mime types. It offers wide flavours of file validation types such as images, videos, audios, documents and archives.

File size units are recognised accurately that includes bytes, kb, mb, gb and tb.

You can define an absolute path to move the file to using the moveTo option. when the file is being, a hashed name is computed for it, and stored on the field such that it can be accessed using the getData() instance method on directly on the instance.

Dealing With Multi-Value Fields and Files

The handler can process multi-value fields and file fields. The field values are stored inside arrays after processing.

Example:

Specifying Accepted File Mimes Extensions

You can specify the accepted mime file extensions during validation. Note that the handler has a FileExtensionDetector module that detects file extension based on its first magic byte. Hence, limiting file extension spoofing errors. Please note that the current list of file magic bytes are still being updated, you can help us by reporting to us more magic bytes codes that are missing.

To specify accepted mimes, use the mimes options.

Example:

Image File Validation

The shortest way to validate image files is to use the image type option. The accepted mimes for images include JPEG, PNG and GIF.

Audio File Validation

The easiest way to validate audio files is to use the audio type option. The accepted mimes for audios include MP3 and others.

Video File Validation

The shortest way to validate video files is to use the video type option. The accepted mimes for videos include MP4, OGG, MOVI, and others.

Media File Validation

The shortest way to validate media files (videos, images and audios) is to use the media type option. The accepted mimes is a combination of video, image and audio mimes.

Document File Validation

The most convenient way to validate document files is to use the document type option. The accepted mimes for documents include DOCX, PDF and DOC, and others.

Archive File Validation

The shortest way to validate archive files is to use the archive type option. The accepted mimes for archives include ZIP, TAR.GZ and TAR, and others.

How To Implement the DBCheckerAbstract Interface

To enable database integrity checks, you must implement two methods on the DBCheckerAbstract class which are the buildQuery() and execute() methods. Then you have to supply an instance of your concrete class as the fourth argument to the Handler.

Below shows how you can do this in Laravel:

Then we can define our own BaseHandler and supply an instance of our concrete class as fourth argument to the parent constructor as shown below:

Hence forth, we can now use 'check' and 'checks' rule options like shown below:

Defining Check and Checks Integrity Rules

The check option defines a single database integrity check while the checks option defines array of database integrity checks.

While defining the rules, one can decide to write the select query to execute. In this case, there should be a query property and the params array property if needed (it defaults to empty array if not given).

The second alternative is to perform the check on a single entity field. In this case, there should be the entity property that references the database table to select from, and the field property that defines the table column to be used in the where clause. If the field property is omitted, It will default to id if the field value is an integer, otherwise, it default to the resolved field name (either camelized or snaked cased depending on the state of the modelCamelizeFields($status) method).

How to Write Your Custom Validation Types

The module is built to be extensible such that you can define more validation methods and use your own custom rule types. You would need to understand some basic things on how the module works. Insecting the ValidatorInterface and the Validator class files is a nice place to start. Below shows how this can be easily achieved.

Define our custom validator that inherits from the main validator:

Then we can define our own BaseHandler that integrates the newly added name type validator method like shown below:

Hence forth, we can now use the name type to validate names like shown below:

The RequiredIf or RequireIf Option

With this option, we can make a field to be mandatory if a given condition is satisfied. Such conditions include:

1. If another field is checked or if it is not checked

2. If another field equals a given value or if it does not equal a given value