NAME

Valiant::Validator::Date - Verify that a value is is a standard Date (YYY-MM-DD)

SYNOPSIS

package Local::Test::Date;

use Moo;
use Valiant::Validations;

has birthday => (is=>'ro');

validates birthday => (
  date => {
    min => sub { pop->years_ago(120) }, # Oldest person I think...
    max => sub { pop->now },
  }
);

my $object = Local::Test::Date->new(birthday=>'2100-01-01');
$object->validate;

warn $object->errors->_dump;

$VAR1 = {
  'birthday' => [
     'chosen date can't be above {{max}}',  # In real life {{max}} would be
                                            # interpolated as DateTime->now
  ]
};

DESCRIPTION

Validates a string pattern to make sure its in a standard date (YYYY-MM-DD) format, which is commonly used in databases as a Date field and its also the canonical pattern for the HTML5 input date type.

Can accept a 'min' and 'max' attribute, which should be either a string in the standard form or a DateTime object.

If you are using the Form helpers the max and min attributes can be reflected into the date input type automatically.

A NOTE ON TIMEZONES

Please keep in mind that a lot of the shortcut helpers just call methods directly on DateTime which means they are using the system timezone. If you are working with dates that are stored in a database you should be aware that the timezone of the database and the timezone of the system running your code might not be the same. This can lead to unexpected results. I don't have a lot of test cases around this, please shout out your experiences if you run into issues. You can use the tz attribute (described below) to set the timezone of the DateTime object we create locally if needed

ATTRIBUTES

This validator supports the following attributes:

tz

Default is 'UTC'.

If you are working with dates that are stored in a database you should be aware that the timezone of the database and the timezone of the system running your code might not be the same. This can lead to unexpected results. You can use the tz attribute to set the timezone of the DateTime object we create locally if needed.

pattern

This is a string pattern that is used by DateTime::Format::Strptime that your date value must conform to (that is it must parse into a DateTime object or the validation fails). The default is '%Y-%m-%d'. This is a common database format and is also used by HTML5 input date type fields.

min

If provided set a bottom limit on the allowed date. Either a string in YYYY-MM-DD format or a DateTime object.

Value may also be a coderef so that you can set dynamic dates (such as always today)

max

If provided set an upper limit on the allowed date. Either a string in YYYY-MM-DD format or a DateTime object.

Value may also be a coderef so that you can set dynamic dates (such as always today)

min_eq

If provided set a bottom limit on the allowed date. Either a string in YYYY-MM-DD format or a DateTime object. The date must be greater than or equal to this value.

Value may also be a coderef so that you can set dynamic dates (such as always today)

max_eq

If provided set an upper limit on the allowed date. Either a string in YYYY-MM-DD format or a DateTime object. The date must be less than or equal to this value.

Value may also be a coderef so that you can set dynamic dates (such as always today)

cb

A code reference that lets you create custom validation logic. This is basically the same as the 'With' validator expect its only called IF the value is in valid date format and you get that date inflated into a DateTime object instead of the raw string value. This makes it a little less work for you since you can skip those extra checks. Also the coderef will receive the validator type instance as the third argument so that you can take advantage of the type helpers (see below \HELPERS).

package MyRecord

use Moo;
use Valiant::Validations;

has attribute => (is=>'ro');

validates attribute => (
  date => +{ 
    min => sub { pop->years_ago(10) },
    max => sub { pop->now },
    cb => \&my_special_method,
  },
);

sub my_special_method {
  my ($self, $dt, $type) = @_;
  # In this case $dt is a DateTime object inflated from the value
  # of 'attribute'.  This method won't get called if we previously 
  # determine that the value isn't in proper YYY-MM-DD format.

  # Custom validation stuff...
}

below_min_msg

above_max_msg

below_min_eq_msg

above_max_eq_msg

invalid_date_msg

The error message / tag associated with the given validation failures. Default messages are provided.

HELPERS

This validator provides the following helpers. These basically just wrap DateTime and DateTime::Format::Strptime so you can avoid having to create your own in your record / object classes.

datetime

Returns a raw blessed DateTime object. If you pass a hash of arguments, those will be passed to new.

now

returns DateTime now.

Please note that now returns a DateTime object that is both the current date AND current time. In the context of a date validator this might be less useful especially for comparisons since a date come out of a storage like a DB will be at hour zero, where as now will likely be after that.

If you want just the current date you should use today. In fact I'd say that today is the more useful of the two in the context of a date validator. I'm leaving now for back compatibility.

today

returns DateTime today. This is the current date at hour zero. If you are writing constraints like 'must be in the past' or 'must be in the future' you probably want to use this method instead of now.

years_ago

years_from_now

Return a DateTime object that is now plus or minus a given number of years.

is_future

is_past

Given a DateTime object (such as the value you are trying to validate), return true or false if it is either in the future or in the past.

SHORTCUT FORM

This validator supports the follow shortcut forms:

validates attribute => ( date => 1, ... );

Which is the same as:

validates attribute => (
  date => +{ },
);

Not many saved characters but makes usage syntactically regular across validators.

You can also invoke a custom callback with a shortcut

validates attribute => ( date => \&my_special_method, ... );

sub my_special_method {
  my ($self, $dt, $type) = @_;
  # Custom validation stuff
}

Which is the same as:

validates attribute => (
  date => +{
    cb => \&my_special_method,
  },
);

Lastly you can specify that the date must be either future or past with a shortcut:

validates attribute => ( date => 'is_future', ... );
validates attribute => ( date => 'is_past', ... );

Which is the same as:

validates attribute => (
  date => +{
    min => sub { pop->is_future },
    max => sub { pop->is_past }
  },
);

GLOBAL PARAMETERS

This validator supports all the standard shared parameters: if, unless, message, strict, allow_undef, allow_blank.

SEE ALSO

Valiant, Valiant::Validator, Valiant::Validator::Each.

AUTHOR

See Valiant

COPYRIGHT & LICENSE

See Valiant

cpanm Valiant

perl -MCPAN -e shell
install Valiant