Data::...Upload(3pm)

💖 NAME 💖

okay so this is Data::...Upload(3pm) (yes that's the man page title, perl does the abbreviating thing, it's fine 💅) and what it actually is, is Data::FormValidator::Constraints::Upload — the module that Validates File Uploads for you, bestie. no cap. 🎀

---

✨ SYNOPSIS ✨

# Be sure to use a CGI.pm or CGI::Simple object as the form
# input when using this constraint
my $q = CGI->new;

use Data::FormValidator::Constraints::Upload qw(
        file_format
        file_max_bytes
        image_max_dimensions
        image_min_dimensions
);
my $dfv = Data::FormValidator->check($q,$my_profile);

# In a Data::FormValidator Profile:
constraint_methods => {
    image_name => [
        file_format(),
        file_max_bytes(10),
        image_max_dimensions(200,200),
        image_min_dimensions(100,100),
     ],
}

---

🌸 DESCRIPTION 🌸

heads up: this module is a new addition to Data::FormValidator and it should be considered "Beta". she's new here. be nice. 🙈

so like, this module is meant to be used in conjunction with the Data::FormValidator module, to automate the task of validating uploaded files. the following validation routines are supplied:

okay and the ✨crucial✨ thing: to use any of them, the input data you pass to Data::FormValidator must be a CGI.pm object. that's the vibe check. no CGI object, no validation, periodt.

---

🦋 file_format

she checks the format of the file, based on the MIME type if it's available, and a case-insensitive version of the file extension otherwise. by default she tries to validate JPEG, GIF and PNG images. the params are:

• an optional hash reference of parameters. a key named mime_types points to array references of valid values.

like so:

file_format( mime_types => [qw!image/jpeg image/gif image/png!] );

calling this function sets some meta data which you can retrieve through the meta() method of the Data::FormValidator::Results object 💖 the meta data added is extension and mime_type.

the MIME type of the file will first be tried to figured out by using the <File::MMagic> module to examine the file. if that doesn't turn up a result, we'll use a MIME type from the browser if one has been provided. otherwise — we give up 😭 the extension we return is based on the MIME type we found, rather than trusting the one that was uploaded. she does her own research, she does not take the upload's word for it. 👑

NOTE: if we have to fall back to using the MIME type provided by the browser, we access it from the original input data and not the filtered data. this should only cause issue when you have used a filter to alter the type of file that was uploaded (e.g. image conversion). so like. iykyk. 🫶

---

🎀 file_max_bytes

she checks the maximum size of an uploaded file. by default, she checks to make sure files are smaller than 1 Meg. the params are:

• reference to max file size in bytes

file_max_bytes(1024), # 1 k

calling this function sets some meta data which you can retrieve through the meta() method of the Data::FormValidator::Results object 💖 the meta data added is bytes.

---

🌈 image_max_dimensions

she checks to make sure an uploaded image is no longer than some maximum dimensions. the params are:

• reference to max pixel width
• reference to max pixel height

image_max_dimensions(200,200),

calling this function sets some meta data which you can retrieve through the meta() method of the Data::FormValidator::Results object 💖 the meta data added is width and height.

---

💜 image_min_dimensions

she checks to make sure an uploaded image is longer than some minimum dimensions. the params are:

• reference to min pixel width
• reference to min pixel height

image_min_dimensions(100,100),

calling this function sets some meta data which you can retrieve through the meta() method of the Data::FormValidator::Results object 💖 the meta data added is width and height.

---

🧚 BACKWARDS COMPATIBILITY

okay so there's an older, more awkward interface to the constraints in this module that's still supported. to use it, you have to load the package with 'validator_packages', and call each constraint in a hashref style, passing the parameters by reference. it looks like this:

validator_packages => [qw(Data::FormValidator::Constraints::Upload)],
constraints => {
    image_name => [
        {
            constraint_method => 'image_max_dimensions',
            params => [\200,\200],
        }
     ],
}

i told you it was more awkward. 💀 that was before i grokked the magic of closures, which is what drives the current interface. the glow up was real. slay. ✨

---

👀 SEE ALSO 👀

FileMetadata, Data::FormValidator, CGI, perl

---

👑 AUTHOR 👑

Mark Stosberg, <mark@summersault.com>

---

📜 COPYRIGHT AND LICENSE 📜

Copyright 2003-2005 by Mark Stosberg

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

---

and that's the whole page bestie!! 🫶 this was perl v5.34.0, dated 2022-06-12, brought to you by the Data::...Upload(3pm) manual — go validate some uploads, you're gonna ate 💅🌸✨