Leaf Form #

During development, you often come across data that should meet some expectations. For example, a user's email address should be a valid email address. Or a user's password should be at least 8 characters long. Unfortunately, you can't always trust the data you deal with, especially when it comes from the user; that's why you need to validate it.

Leaf provides a clean and simple interface to validate and use incoming data. We call this Leaf Form. It's not a form builder, it's not a form renderer, it's just a simple data validation library.

Installation #

You can quickly install Leaf Form using the Leaf CLI:

leaf install form

Or via composer:

composer require leafs/form

Validating data #

Leaf Form comes with a very handy validate() method that allows you to validate data. It takes in two arguments:

• An array of the data to validate
• The rules to validate the data against

If the validation fails, the validate() method will return false. Otherwise, it will return the validated data.

<?php

use Leaf\Form;

$data = [
  'name' => 'Full Name',
  'email' => 'mail@example.com',
  'password' => 'password',
];

$validated = Form::validate($data, [
  'name' => 'text',
  'email' => 'email',
  'password' => 'min:8',
]);

if ($validated) {
  // data is valid
  $email = $validated['email'];
} else {
  // data is invalid
}

<?php

$data = [
  'name' => 'Full Name',
  'email' => 'mail@example.com',
  'password' => 'password',
];

$validated = form()->validate($data, [
  'name' => 'text',
  'email' => 'email',
  'password' => 'min:8',
]);


if ($validated) {
  // data is valid
  $email = $validated['email'];
} else {
  // data is invalid
}

If the data is invalid, you can return the reason why the validation failed using the errors() method.

<?php

use Leaf\Form;

...

$validated = Form::validate($data, [
  'name' => 'text',
  'email' => 'email',
  'password' => 'min:8',
]);

if ($validated) {
  // data is valid
} else {
  $errors = Form::errors();
  // data is invalid
}

<?php

$validated = form()->validate($data, [
  'name' => 'text',
  'email' => 'email',
  'password' => 'min:8',
]);

if ($validated) {
  // data is valid
} else {
  $errors = form()->errors();
  // data is invalid
}

Request Validation #

Leaf allows you to validate request data directly on the request object. Using this method, you will interface with Leaf's request object instead of Leaf form which means you can use it without manually installing Leaf Form. To get started, all you need to do is call validate() on the request object.

<?php

$app = new Leaf\App;

...

$app->post('/register', function() use($app) {
  $validatedData = $app->request()->validate([
    'name' => 'text',
    'email' => 'email',
    'password' => 'min:8',
  ]);

  if (!$validatedData) {
    $errors = $app->request()->errors();
  }
});

<?php

app()->post('/register', function() {
  $validatedData = request()->validate([
    'name' => 'text',
    'email' => 'email',
    'password' => 'min:8',
  ]);

  if (!$validatedData) {
    $errors = request()->errors();
  }
});

Note that you don't need to pass in the data to validate. The request object will automatically get the data from the request.

Optional Fields #

By default, all fields are required. If you want to make a field optional, you can add the optional rule to the field. Once a field is optional, it will only be validated if it is present in the data and not null.

Form::validate($data, [
  'bio' => 'optional|text',
]);

form()->validate($data, [
  'bio' => 'optional|text',
]);

Available Rules #

Leaf Form comes with a number of built-in rules that you can use to validate data. Here's a list of all the available rules:

Passing Parameters To Rules #

Some rules like min, max, between, match, contains, in and regex require additional parameters. You can pass these parameters to the rules by separating them with a colon (:).

Form::validate($data, [
  'bio' => 'min:10',
]);

form()->validate($data, [
  'bio' => 'min:10',
]);

Some rules like between and in require multiple parameters. You can pass these parameters by using an array.

Form::validate($data, [
  'bio' => 'between:[18,30]',
]);

form()->validate($data, [
  'bio' => 'between:[18,30]',
]);

Array Validation #

Leaf provides easy ways to validate arrays of data. You can validate an array of data using the array() validator. You can also validate the items in an array using the dot notation.

array() #

The array() validator allows you to validate an array of data. This checks if the data is an array and if it contains the specified rules.

Form::validate($data, [
  'users' => 'array()',
]);

form()->validate($data, [
  'id_numbers' => 'array()',
]);

The example above will check if the users field is an array. Let's say you want to check if the array contains only numeric values. You can do that by passing in the rules to the array() validator.

Form::validate($data, [
  'id_numbers' => 'array(number)',
]);

form()->validate($data, [
  'id_numbers' => 'array(number)',
]);

The array(<rule>) method should not be used on arrays with key => value pairs.

Dot Notation #

You can also validate the items in an array using the dot notation. This allows you to validate arrays with key => value pairs. For example, let's say you have an array holding a user with a name and an email address:

$data = [
  'user' => [
    'name' => 'John Doe',
    'email' => 'john@example.com',
  ],
];

You can validate the user's name and email address like this:

Form::validate($data, [
  'user.name' => 'text',
  'user.email' => 'email',
]);

form()->validate($data, [
  'user.name' => 'text',
  'user.email' => 'email',
]);

Custom Rules #

You can create your own rules using the addRule() method or it's alias rule(). It takes in three arguments:

• The name of the rule
• The rule's handler
• The rule's error message

Note: The rule's handler must be either a regular expression or a callable that returns a boolean value.

Form::addRule('isEven', '/^\d*[02468]$/', 'The :attribute must be an even number.');

Form::rule('superTest', function ($value) {
  // in functions, you can also add the error messages like this
  Form::message('superTest', '{field} should be superTest!');

  return $value === 'superTest';
});

...


Form::validate($data, [
  'age' => 'isEven',
]);

form()->rule('isEven', '/^\d*[02468]$/', 'The {field} must be an even number.');

form()->rule('superTest', function ($value) {
  // in functions, you can also add the error messages like this
  form()->message('superTest', '{field} should be superTest!');

  return $value === 'superTest';
});

...


form()->validate($data, [
  'age' => 'isEven',
]);

Custom Error Messages #

You can customize the error messages for each rule by passing in an array of the rules and their error messages to the message() method. The keys of the array should be the names of the rules and the values should be the error messages.

Form::message([
  'required' => '{field} is required',
  'email' => '{field} must be a valid email address',
]);

form()->message([
  'required' => '{field} is required',
  'email' => '{field} must be a valid email address',
]);

You can also customize the error messages for any rule by passing in the rule's name and the error message to the message() method.

Form::message('required', '{field} is required');

form()->message('required', '{field} is required');

Note the use of {field}. This is a mini template that tells leaf to replace {field} with the current field. So in this case:

Form::message('required', '{field} is required');
Form::validate($data, [
  'name' => 'required',
]);

form()->message('required', '{field} is required');
form()->validate($data, [
  'name' => 'required',
]);

The error message will be name is required. You can also use {Field} instead of {field} to get the field name with the first letter capitalized. You can also use {value} to get the value of the field.