NAME

Valiant::Validates - Role that adds class and instance methods supporting validations

SYNOPSIS

See Valiant.

DESCRIPTION

This is a role that adds class level validations to you Moo or Moose classes. The main point of entry for use and documentation currently is Valiant. Here we have API level documentation without details or examples. You should read Valiant first and then you can refer to documentation her for further details.

In addition to methods this class provides, it also proves all methods from Valiant::Translation

CLASS METHODS

validates

Used to declare validations on an attribute. The first argument is either a scalar or arrayref of scalars which should be attributes on your object:

__PACKAGE__->validates( name => (...) );
__PACKAGE__->validates( ['name', 'age'] => (...));

Following arguments should be in one of three forms: a coderef or subroutine reference that contains validation rules, a key - value pair which is a validator class and its arguments or lastly you can pass in a Type::Tiny constraint directly. You may also have key value pairs which are global arguments for the validate set as a whole:

package Local::Model::User;

use Moo;
use Valiant::Validations; # Importer that wraps Valiant::Validates
use Types::Standard 'Int';

has ['name', 'age'] => (is=>'ro);

validates name => (
  length => { minimum => 5, maximum => 25 },
  format => { match => 'words' },
  sub {
    my ($self, $attribute, $value, $opts) = @_;
    $self->errors->add($attribute, "can't be Joe.  We hate Joe :)" ,$opts) if $value eq 'Joe';
  }, +{ arg1=>'1', arg2=>2 }, # args are optional for coderefs but are passed into $opts
  \&must_be_unique,
);

validates age => (
  Int->where('$_ >= 65'), +{
    message => 'A retiree must be at least 65 years old,
  },
  ..., # additional validations
);

sub must_be_unique {
  my ($self, $attribute, $value, $opts) = @_;
  # Some local validation to make sure the name is unique in storage (like a database).
}

If you use a validator class name then the hashref of arguments that follows is not optional. If you pass an options hashref it should contain arguments that are defined for the validation type you are passing or one of the global arguments: on, message, if and unless. See "GLOBAL OPTIONS" for more.

For subroutine reference and Type::Tiny objects you can or not pass an options hashref depending on your needs. Additionally the three types can be mixed and matched within a single validates clause.

When you use a validator class (such as length = { minimum => 5, maximum => 25 }>) we resolve the class name length in the following way. We first camel case the name and then look for a 'Validator' package in the current class namespace. If we don't find a match we check each namespace up the hierarchy and then check the two global namespaces Valiant::ValidatorX and Validate::Validator. For example if you declare validators as in the example class above Local::Model::User we would look for the following:

Local::Model::User::Validator::Length
Local::Model:::Validator::Length
Local::Validator::Length
Validator::Length
Valiant::ValidatorX::Length
Valiant::Validator::Length

These get checked in the order above and loaded and instantiated once at setup time.

NOTE: The namespace Valiant::Validator is reserved for validators that ship with Valiant. The Valiant::ValidatorX namespace is reserved for additional validators on CPAN that are packaged separately from Valiant. If you wish to share a custom validator that you wrote the proper namespace to use on CPAN is Valiant::ValidatorX.

You can also prepend your validator name with '+' which will cause Valiant to ignore the namespace resolution and try to load the class directly. For example:

validates_with '+App::MyValidator';

Will try to load the class App::MyValidator and use it as a validator directly (or throw an exception if it fails to load).

validates_with

validates_with is intended to process validations that are on the class as a whole, or which are very complex and can't easily be assigned to a single attribute. It accepts either a subroutine reference with an optional hash of key value pair options (which are passed to $opts) or a scalar name which should be a stand alone validator class (basically a class that does the validates method although you should consume the Validate::Validator role to enforce the contract).

__PACKAGE__->validates_with(sub {
  my ($self, $opts) = @_;
  ...
});

__PACKAGE__->validates_with(\&check_object => (arg1=>'foo', arg2=>'bar'));

sub check_object {
  my ($self, $opts) = @_;
  ...
}

__PACKAGE__->validates with('Custom' => (arg1=>'foo', arg2=>'bar'));

If you pass a string that is a validator class we resolve its namespace using the same approach as detailed above for validates. Any arguments are passed to the new method of the found class excluding global options.

INSTANCE METHODS

validate

Run validation rules on the current object, optionally with arguments hash. If validation has already been run on this object, we clear existing errors and run validations again. Currently the return value of this method is not defined in the API. Example:

$object->validate(%args);

Currently the only arguments with defined meaning is context, which is used to defined a validation context. All other arguments will be passed down to the $opts hashref.

validate_only

$obj->vadate_only('name', context=>'create');
$obj->validate_only(['name', 'age'], context=>'update');

Similar to validate but will run only those validations that are associated with the named attribute(s). Access either a single string or arrayref of strings. Please keep in mind that fields or custom validations can add errors to other fields so you may still need to check all fields for errors after running this method in order to get a full picture of the object validation state. However this method can be of use if you are doing AJAX per field form validation, for example.

valid

invalid

Return true or false depending on if the current object state is valid or not. If you call this method and validations have not been run (via validate) then we will first run validations and pass any arguments to "validates". If validations have already been run we just return true or false directly UNLESS you pass arguments in which case we clear errors first and then rerun validations with the arguments before returning true or false.

has_errors

Returns a boolean indicating if the object currently has errors. This does not run a validation check first (unlike valid or invalid). So if you just want to check the current state of the errors list and not tamper with that state you can use this.

clear_validated

Clears any errors and sets the object as though validations hd never been run.

do_validate

Sets skip_validation to true and returns $self

skip_validate

Sets skip_validation to false and returns $self

context

Set a validation context (or arrayref of contexts) that will be used on an following validations.ß

ATTRIBUTES

errors

An instance of Valiant::Errors.

validated

This attribute will be true if validations have already been been run on the current instance. It merely says if validations have been run or not, it does not indicate if validations have been passed or failed see "valid" pr "invalid"

skip_validation

When true do not run validations, even if you call ->validate

AUTHOR

John Napiorkowski email:jjnapiork@cpan.org

SEE ALSO

Valiant::Validations

COPYRIGHT & LICENSE

Copyright 2020, John Napiorkowski email:jjnapiork@cpan.org

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Valiant

perl -MCPAN -e shell
install Valiant