NAME

Form::Tiny::Manual - reference for working with Form::Tiny

SYNOPSIS

# first ...
package SomeForm;

use Form::Tiny;
use Types::Common::String qw(SimpleStr);
use Types::Common::Numeric qw(PositiveInt);

form_field 'name' => (
	type => SimpleStr,
	adjust => sub { ucfirst pop },
	required => 1,
);

form_field 'lucky_number' => (
	type => PositiveInt,
	required => 1,
);

form_hook cleanup => sub {
	my ($self, $data) = @_;

	$self->add_error('Perl6 is now Raku')
		if $data->{name} eq "Perl"
		&& $data->{lucky_number} == 6;
};

# then ...

use Data::Dumper;
my $form = SomeForm->new;

$form->set_input({
	name => 'perl',
	lucky_number => 6,
});

if ($form->valid) {
	print Dumper $form->fields;
}
else {
	print Dumper $form->errors;
	print Dumper $form->errors_hash;
}

DESCRIPTION

Form::Tiny is a form validation engine which can use all the type constraints you're already familiar with. The module does not ship with any field definitions on its own, instead it provides tools to reuse any type constraints from Type::Tiny and other similar systems.

Form::Tiny is designed to be a comprehensive data validation and filtering system based on existing validation solutions. Type::Tiny libraries cover most of the validation and coercion needs in models, and now with Form::Tiny they can be empowered to do the same with input data.

The module itself isn't much more than a hashref filter - it accepts one as input and returns the transformed one as output. The pipeline for a single field is as follows:

input
  |
  |--> filtering -- coercion -- validation -- adjustment --|
                                                           v
                                                        output

(Note that not every step on that pipeline is ran every time - it depends on form configuration)

The module always tries to get as much data from input as possible and copy that into output. It will never copy any data that is not explicitly specified in the form fields configuration.

Moose-like form domain-specific language

Form::Tiny allows you to define forms much like you would define a Moose class. The syntax is showcased below:

use Form::Tiny -filtered;
use Types::Standard qw(Enum Str);

form_trim_strings;
form_message Required => 'This one is mandatory!';

form_field 'url' => (
	type => Str,
	required => 1,
);

form_field 'action' => (
	type => Enum[qw(GET POST PUT DELETE)],
	default => sub { 'GET' },
);

form_hook cleanup => sub {
	my ($self, $data) = @_;
	... # perform cleaning
};

Adding a use Form::Tiny line will cause your current package to be turned into a form by composing Form::Tiny::Form into it (and as a result, merging all of its symbols with your package). It also imports Moo into your namespace for convenience (unless you specify -nomoo flag). Refer to "Available import flags" in Form::Tiny for a full list of available flags.

This syntax is designed to resemble and mix in nicely with Moo/se syntax. Form fields and class properties are completely separate and can be freely intermixed with each other.

A full list of DSL keywords is available in "Form domain-specific language" in Form::Tiny.

Basic usage

Input can be passed as a scalar to the constructor or with the set_input method. Every call to that method will cause the form instance to be cleared of old errors and fields, so that it can be used again for different data.

use MyForm;

# either ...
my $form = MyForm->new(input => $data);

# or ...
my $form = MyForm->new;
$form->set_input($data);

With input in place, a valid method can be called, which will return a validation result and fill in the errors and fields properties. These properties are mutually exclusive: errors are only present if the validation is unsuccessful, otherwise the fields are present.

The example below illustrates how a form class could be used to validate data.

use MyForm;

my $form = MyForm->new;
$form->set_input($some_input);

if ($form->valid) {
	my $fields = $form->fields; # a hash reference
	...
} else {
	my $errors = $form->errors; # an array reference
	my $errors_hash = $form->errors_hash; # a hash reference
	...
}

$form->fields returns a hash reference which can be used to access validated and fields, but that might often be suboptimal. Using a hash reference by hand opens up possibilities of other errors, such as typos in field names.

Alternatively, $form->value can be used to access a value of a single field:

if ($form->valid) {
	my $first = $form->value('first_field_name');
	my $other = $form->value('other_field_name');
}

If the field name was misspelled, an exception will be raised. Refer to "value" in Form::Tiny::Form for details.

Form building

You can use form_field function to declare form fields, just like you would use has to declare class properties in Moo/se.

form_field 'some_name';
form_field 'another_name' => (
	required => 'soft',
);

Form fields end up as instances of Form::Tiny::FieldDefinition or its descendants. Also see full keyword docs at "form_field" in Form::Tiny.

The only required element in hashes defining the fields is the key name, which contains the string with name of the field in the form input. In the most basic style of form_field, the name should not be given explicitly, as it will be automatically overwritten by the first argument to that function. Other possible elements are:

type

form_field 'with_type' => (
	type => SomeType,
);

The type that the field will be validated against. Effectively, this needs to be an object with validate and check methods implemented. All types from Type::Tiny type libraries, as well as all Form::Tiny forms meet this criteria.

coerce

form_field 'coerced' => (
	type => Int->plus_coercions(Num, q{ int($_) }),
	coerce => 1, # uses coerce from the type
);

form_field 'also_coerced' => (
	coerce => sub {
		my ($self, $value) = @_;
		return int($value);
	}
);

A coercion that will be made before the type is validated and will change the value of the field. This can be a coderef or a boolean:

Value of 1 means that coercion will be applied from the specified type. This requires the type to also provide coerce and has_coercion method, and the return value of the second one must be true.

Value of 0 means no coercion will be made. This is the default behavior.

Value that is a coderef will be passed ($self, $value). It is required to make its own checks and return a scalar which will replace the old value.

adjust

form_field 'adjusted' => (
	type => Str,
	adjust => sub {
		my ($self, $value) = @_;
		return lc($value);
	},
);

An adjustment that will be made after the type is validated and the validation is successful. This must be a coderef that gets passed the validated value and returns the new value for the field (just like the coderef version of coercion).

At the point of adjustment, you can be sure that the value passed to the coderef meets the type constraint specified. It's probably a good idea to provide a type along with the adjustment to avoid unnecessary checks in the subroutine - if no type is specified, then any value from the input data will end up in the coderef.

required

form_field 'soft_required' => (
	required => 'soft',
);

Controls if the field should be skipped silently if it has no value or the value is empty. Possible values are:

0 - The field can be non-existent in the input, empty or undefined. This is the default behavior

"soft" - The field has to exist in the input, but can be empty or undefined

1 or "hard" - The field has to exist in the input, must be defined and non-empty (a value 0 is allowed, but an empty string is disallowed)

default

form_field 'has_default' => (
	default => sub {
		my $form = shift;
		return 'this is a default value'
	},
);

A coderef, which should return a scalar value that will be used in place of a non-existent input value. If the field is marked as hard-required as well, the default value will also replace undefined or empty values. It gets passed a single parameter, which is the form instance.

The default value does not support nested arrays, like array.*. An exception will be thrown at compile time if this condition is not met.

message

form_field 'custom_message' => (
	type => Int,
	message => 'should be an integer',
);

A static string that should be used instead of an error message returned by the type when the validation fails. Can also be an object that overloads stringification.

It can be useful since not all Type::Tiny error messages are meant to be readable for end users. It can also come in handy when the error messages need to be localized.

data

While building your form fields, it's possible to save some extra data along with each field. This data can be used to prompt the user what to input, insert some HTML generation objects or store hints on how to fill the field properly.

form_field "first name" => (
	type => NonEmptySimpleStr,
	data => {
		element => "input",
		properties => {
			type => "text",
		},
	},
);

The data field can hold any value you want and later retrieved with an instantiated form object:

for my $definition (@{$form->field_defs}) {
	say "field: " . $definition->name;
	say "data: " . Dumper($definition->data);
}

Context

While defining your form, the module keeps track of the context in which you're using certain keywords. After each form_field which is not dynamic, the context is set to that field until the next DSL keyword. Other keywords can either use that context or reset it.

use Form::Tiny;

# no context yet

form_field 'my_field';

# 'my_field' context

form_hook cleanup => sub { ... };

# no context since it has been reset

Keywords that are using the context are:

field_validator

form_field 'my_field';
field_validator 'something went wrong' => sub { ... };

field_filter

form_field 'my_field';
field_filter Str, sub { ... };

Additional validators

Having types for fields is great, but often a need arise to have more validators than just a type. While in theory you can create a subtype that will satisfy that need, it can prove to be hard to get right. Instead, you can specify multiple field validators:

form_field 'positive_even_int' => (
	type => Int,
	message => 'must be an integer',
);

field_validator 'must be even' => sub {
	my ($self, $value) = @_;
	return $value % 2 == 0;
};

field_validator 'must be positive' => sub {
	pop() > 0
};

Validators consist of two parts - an error message that should be added to form in case validation fails, and a subroutine that will perform the check. This subroutine is passed ($self, $value), and should return a boolean value - validation result.

Additional validations will take place after the type is validated, and only if the type validation is successful. This means that:

these errors will not always end up in the error messages
you do not have to manually validate the value passed to the subroutines

Hooks

form_hook HOOK_NAME => $coderef;

Hooks are the way to introduce more behavior to the form, not achievable with single field validation. Each type of hook can have multiple code references assigned to it, and they will fire in the order of declaration.

Each hook type defines its own set of parameters that get passed to the $coderef. Most hooks require you to return they last parameter that got passed and you're free to change it however you like. If a hook does not require you to return the value, the return value is discarded.

Hook types are listed below:

cleanup

While regular properties allow for single-field validation, sometimes a need arises to check if some fields are synchronized correctly, or even to perform some more complex validation. This can be done with the cleanup hook, which will be only fired once after the validation for every individual field was successful. The cleaner subroutine should look like this:

sub {
	my ($self, $data) = @_;

	# do something with $data
	# call $self->add_error if necessary

	# no need to return
};

A subroutine like the one above should either be specified in a form_hook or in a form_cleaner shortcut.

# either ...
form_hook cleanup => sub { ... };

# or ...
form_cleaner sub { ... };

Cleaning sub is also allowed to change $data, which is a hash reference to the running copy of the input. Note that this is the final step in the validation process, so anything that is in $data after the cleanup will be available in the form's fields after validation. The hook coderef doesn't have to return $data, as it is a hash reference and will be updated just by changing its contents.

before_mangle

before_mangle is fired for every field, just before it is changed ("mangled"). In addition to an object instance, this method will be passed the definition of the field (Form::Tiny::FieldDefinition) and a scalar value of the field. The field must exist in the input hash for this method to fire, but can be undefined. The return value of this method will become the new value for the field.

form_hook before_mangle => sub {
	my ($self, $field_definition, $value) = @_;

	# do something with $value

	# don't forget to return!
	return $value;
};

before_validate

before_validate is fired just once for the form, before any field is validated. It is passed a hash reference - the input data. This method is free to do anything with the input.

form_hook before_validate => sub {
	my ($self, $input_data) = @_;

	# do something with $input_data

	# no need to return
};

This hook does not require you to return anything and is passed the same data as cleanup. Note that it will not be fired if the input data was not a hash reference.

after_validate

Same as cleanup, but differs in two aspects:

it is ran before cleanup
it is ran regardless of previous validation being successful or not, but only if the data format is correct

This hook does not require you to return anything and is passed the same data as cleanup.

reformat

Same as before_validate, but differs in two aspects:

it is ran before data is rejected due to not being a hash reference
its return value is used for the rest of the validation process as input

This hook does require you to return a new input value to the validation. It is passed the same data as before_validate.

Note: This hook is ran inside a try/catch block, so you can throw an exception inside in order to stop form validation if the input is malformed. This will add Form::Tiny::Error::InvalidFormat error to the form.

after_error

form_hook after_error => sub {
	my $form_instance = shift;
	my $error_instance = shift;

	if ($error_instance->field eq 'some_field') {
		$error_instance->set_error('new error message');
	}

	# no need to return
};

Called after an error has been added to the form. Gets passed two arguments: object instance and a newly created error instance. Can be used to log/debug or transform error messages in any way, like internationalize them.

This hook does not require you to return anything.

Optional behavior

The module provides optional predefined behaviors which can be enabled with an import flag.

Strict mode

Turned on by Form::Tiny::Plugin::Strict plugin or with the -strict flag in Form::Tiny.

Enables strict mode for the form. Validation will fail if form input contains any data not specified in the field definitions. This additional check is added to the form as a before_validate hook.

Strict mode is helpful when you want to make sure you're not getting any extra data in your input. It does not affect the output of forms, only the validation result. Form::Tiny does not copy fields that are not declared explicitly to output regardless of the strict mode being turned on.

For example, if your form contains many optional fields which change often, you may want to ensure that your users are not sending anything you're not going to handle. This can help debugging and prevent errors.

Important note: Strict mode will cause the system to crawl your entire input data to search for any odd elements. This will cause validation to only run at about half the speed, and more importantly it will not be able to cope with circular references (even weakened). If your input data may contain circular references you should not make use of the strict mode.

Filters

Turned on by Form::Tiny::Plugin::Filtered plugin or with the -filtered flag in Form::Tiny.

Enables initial filtering for the input fields. This behavior is added to the form as a before_mangle hook.

The filtering system performs a type check on field values and only apply a filtering subroutine when the type matches. This is done before the validation, and so can affect the validation result. Filters behave much like type coercion, but they are more flexible and can be stacked by having multiple filters for the same field, each using value returned by the previous one.

Filter subroutines should accept two parameters: ($self, $value), and must return a $value, changed or unchanged.

An example filter that turns integers into their absolute values:

form_filter Int, sub {
	my ($self, $value) = @_;
	return abs $value;
};

A filter can be also narrowed down to a single form field with field_filter keyword, which will apply to the last field declared:

form_field 'my_field';
field_filter Int, sub { abs pop() };

One special keyword exists for string trimming using the filters system:

form_trim_strings;

When the field is filtered, the form filters are applied before field filters. Each type of filter is applied in the order they were defined.

Plugins

Form::Tiny can be extended with plugins:

use Form::Tiny plugins => [qw(Plugin1 +Namespace::Plugin2)];

Added behavior is entirely up to the plugin. See Form::Tiny::Plugin for details on how to implement a plugin.

Inline forms

The module enables a way to create a form without the need of a dedicated package. This is done with the Form::Tiny::Inline class. This requires the user to pass all the data to the constructor, as shown in the example:

my $form = Form::Tiny::Inline          #     An inline form ...
           ->is(qw/strict filtered/)   # ... with Strict and Filtered plugins ...
           ->new(                      # ... will be created with properties:
	fields => {my_field => { ... }},
	cleaner => sub { ... },
);

The possible constructor arguments:

fields (hashref of hashrefs)
field_defs (aref of hashrefs) (legacy)
filters (aref of arefs, only when filtered)
cleaner (coderef)

The same syntax as for regular helpers will work.

There are some limitations though.

There's no way to define custom hooks (other than a single cleaner) in inline forms. Additionally, a special case exists for the filtered inline forms, as they will act as if you declared form_trim_strings in their classes.

Additionally, inline forms are much slower, since they have to recompile every time, which means they are mostly useful for quick prototyping.

Advanced topics

Nesting

A dot (.) can be used in the name of a field to express hashref nesting. A field with name => "a.b.c" will be expected to be found under the key "c", in the hashref under the key "b", in the hashref under the key "a", in the root input hashref.

This is the default behavior of a dot in a field name, so if what you want is the actual dot it has to be preceded with a literal backslash (\., which is '\\.' in a string). Additionally, having a literal backslash in field name requires you to escape it as well (\\, which is '\\\\' in a string).

Nested arrays

Nesting adds many new options, but in the example above we're only talking about hashes. Regular arrays can of course be handled by ArrayRef type from Type::Tiny, but that's a hassle and makes it impossible to have any deeper structure defined in a name. Instead, you can use a star (*) as the only element inside the nesting segment to expect an array there. Adding named fields can be resumed after that, but needn't.

For example, name => "arr.*.some_key" expects arr to be an array reference, with each element being a hash reference containing a key some_key. Note that any array element that fails to contain wanted hash elements will cause the field to be ignored in the output (since input does not meet the specification entirely). If you want the validation to fail instead, you need to make the nested element required.

# This input data ...
{
	arr => [
		{ some_key => 1 },
		{ some_other_key => 2 },
		{ some_key => 3 },
	]
}

# Would not get copied into output and ignored,
# because the second element does not meet the specification.
# Make the element required to make the validation fail instead

Other example is two nested arrays that not necessarily contain a hash at the end: name => "arr.*.*". The leaf values here can be simple scalars.

If you want a hash name consisted of star character * alone, you can prepend it with a literal backslash, much like the nesting operator: \*, which in perl string must be written as '\\*'

Nested forms

Every form class created with Form::Tiny is a consumer of Form::Tiny::Form role, and can be used as a field definition type in other form. The outer and inner forms will validate independently, but inner form errors will be added to outer form with the outer field name prepended.

# in Form2
# everything under "nested" key will be validated using Form1 instance
# every error for "nested" will also start with "nested"
form_field "nested" => (
	type => Form1->new,
);

A couple of important details:

subform will not validate at all if no value was present in main form input

This means that even if subform had required fields, errors will not be added to the main form if they are missing. Remember to make your subform required in the main for if it is not the behavior you want!
specifying message for the field will completely replace subform's field errors

A single error with the message will be added instead of list of subform errors.
default value for the subform must be its valid input

It will be used to determine the default values for fields of the subform. As with regular default values, it will not use filters, coercions or adjustments from the main form field.
resulting field will only contain what subform's fields contain

No extra values not defined in the subform will be copied.

Form inheritance

It is possible for Form::Tiny forms to inherit from one another, but the feature is experimental (meaning it does work, but is not tested enough and may not work properly for certain configurations).

# ParentForm.pm
package ParentForm;

use Form::Tiny;

form_field 'inherited_field';

1;

# ChildForm.pm
package ChildForm;

use Form::Tiny;

# regular 'extends' from Moo
# must be specified before any DSL call
extends 'ParentForm';

# should now have 'inherited_field' and any fields defined below:

...

1;

It is required that class parents are specified before any calls to Form::Tiny DSL have been made. If there are no DSL calls, a special keyword must be used: see "Empty forms" in Form::Tiny::Manual::Cookbook.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)