sFire PHP Framework

Uploaded Files Validator

sFire File Validator lets you easily validate uploaded files submitted by a form. It comes with handy built-in validator rules and you may also build your own (extending). You can validate extensions, sizes and more and set you own custom error messages.

In this section we will handle:

  • Creating a new validator instance
  • Adding form input fields for validation
  • Execute the validation and retrieve the error messages
  • The special required rule
  • All other rules (11 rules)
  • Custom messages
  • Custom validator functions

Create a new instance

Creating an instance of the validator is as simple as this:

use sFire\Validator\File\Validator;

$validator = new Validator();

The constructor accepts one optional argument named prefix.

Prefix parameter

The first argument is the prefix and will handle all the field names that are built as an Array like:

<input type="file" name="image[big]">
<input type="file" name="image[small]">

Just add the "image" as prefix and you can point to the file without writing the full name:

$validator = new Validator('image');
$validator -> field('big');
$validator -> field('small');

Adding form input fields for validation

By using the field method, you can add one or more input field names for validation.

$validator = new $validator();

//You can add a single fieldname
$validator -> field('fieldname');

//You can also add multiple fields
$validator -> field('fieldname-1', 'fieldname-2'));

Now you can add one or multiple rules to a field.

Execute validation

sFire File Validator comes with great built-in validation rules. To apply a rule you can do the following:

$validator = new Validator();

//In this example we will use the minsize rule
$validator -> field('fieldname') -> minsize(5000);

//Fails
if(true === $validator -> fails()) {
    print_r($validator -> getMessages()); //Get the error messages
}

//Passes
if(true === $validator -> passes()) {
    //Validation success
}

Chaining

You may also apply multiple rules by chaining them.

$validator = new Validator();
$validator -> field('fieldname') -> minsize(5000) -> maxsize(10000) -> extension('jpg', 'png');

Retrieve all error messages

You can use the getMessages method to return an Array with errors. This method accepts one parameter as a Boolean to retrieve the full names or short names of the error fields. This only works when you set the prefix in the validator instance. Default is false (short names).

HTML
<input type="file" name="image[small]">
PHP
$validator = new Validator('image');
$valdiator -> field('small') -> minsize(5000);

if($validator -> fails()) {

    $validator -> getMessages(); //Output: [small: "File size must be greater than 5000 bytes"]
    $validator -> getMessages(true); //Output: [image[surname]: "File size must be greater than 5000 bytes"]
}

Retrieve single error messages

You may also retrieve a single error message:

HTML
<input type="file" name="image[small]">
PHP
$validator = new Validator();
$valdiator -> field('image[small]') -> minsize(5000);

if($validator -> fails()) {
    $validator -> getMessage('image[small]'); //Output: "File size must be greater than 5000 bytes"
}

Special rule "required"

Before explaining all the rules, you need to know the existence of the required rule. This rule is a special rule because you can enable and disable other rules based on if the file has been submitted or not.

For example, if an image is optional and thus not required, you can set the required to Boolean false. If the user leaves the file input blank, it will not validate the file:

$validator = new Validator();
$valdiator -> field('fieldname') -> required(false) -> size(2000, 5000);

Note: the "required" method should always comes before other rules.

Validation rules

Below is a list of all the validation rules.

Dimensions

Check whenever an image has a given width and height in pixels.

$validator -> field('fieldname') -> dimensions(150, 300); //Width and height
Extension

Check whenever a file has a valid extension. You can give one extension or multiple separated by a comma.

$validator -> field('fieldname') -> extension('jpg'); //You can also use ".jpg"
$validator -> field('fieldname') -> extension('jpg', 'png', 'gif'); //Or seperate them as parameters
Failed

It is always good to check if a file upload has failed. The failed rule will check for the following error messages:

  • File exceeds the maximum file size that was specified in the HTML form
  • File was only partially uploaded
  • No file was uploaded
  • Missing a temporary folder
  • Failed to write file to disk
  • An extension stopped the file upload
$validator -> field('fieldname') -> failed();
Maximum height

Check whenever an image has exceeded a given maximum height in pixels.

$validator -> field('fieldname') -> maxheight(300);
Maximum size

Check whenever a file has exceeded a given maximum file size in bytes.

$validator -> field('fieldname') -> maxsize(5000);
Maximum width

Check whenever an image has exceeded a given maximum width in pixels.

$validator -> field('fieldname') -> maxwidth(150);
Minimum height

Check whenever an image is at least a given height in pixels.

$validator -> field('fieldname') -> minheight(200);
Minimum size

Check whenever the file size of a file is a given minimum in bytes.

$validator -> field('fieldname') -> minsize(2000);
Minimum width

Check whenever an image is at least a given width in pixels.

$validator -> field('fieldname-one' -> minwidth(100);
Not extension

Check whenever a file has not a given extension. You can give one extension or multiple separated by a comma.

$validator -> field('fieldname') -> notextension('jpg'); //You can also use ".jpg"
$validator -> field('fieldname') -> notextension('jpg', 'png', 'gif'); //Or separate them as parameters
Size

Check whenever the file size of a file is a given minimum and maximum in bytes.

$validator -> field('fieldname') -> size(2000, 5000); //Minimum and maximum size in bytes

Custom messages

Each validation rule has its own error message. If you want to set a custom message per rule or even per rule in combination with a field, you may do so.

Custom message per rule

Set custom error message for all fields with the size rule. You can inject the parameter using the %s characters. To escape this, you can add an extra "%" character.

$validator = new Validator();
validator -> field('amount') -> size(2000, 5000);
validator -> setMessage() -> size('File size has to be between %s and %s bytes'); //Outputs "File size has to be between 2000 and 5000 bytes"

Custom message per rule and per field

Set custom error message for the "image" field with the size rule.

$validator = new Validator();
validator -> field('image') -> size(2000, 5000);
validator -> setMessage('image') -> size('File size has to be between %s and %s bytes'); //Outputs "File size has to be between 2000 and 5000 bytes"

Custom validator functions

sFire File Validator has a lot of built-in validation rules. But if you want for example check if a file already exists as a blob in a database, you have to build your own validation rule. You may use the extend method to build a custom validation rule or use the load method to load your own validation rule from a validation file.

Extending

The extend function accepts a minimal of three parameters. The first parameter will be the field name. The second parameter is a callable function and the third parameter is the error message when the validation fails.

The callable function (second parameter) will be injected with two parameters. The field name and the file as an Array.

$validator = new Validator();
$validator -> extend('fieldname', function($field, $file) {

    return $file['type'] === 'image/png';

}, 'File is not a PNG image');

if(true === $validator -> passes()) {
    //Validation success
}

Loading validation file

You can load your own validation files. Check the validation file documentation for more information.