Uploading Files

This document provides methods and examples for uploading files with Formr.

Formr's method of uploading and resizing files is fairly simplistic: Formr will provide basic security in renaming uploaded file names - by stripping out anything that's not a letter, number or underscore - and allows for the checking of mime types and/or file extensions.

Using Another Script for File Uploads

File uploads with Formr may satisfy most people's uploading needs, however, if your file operations are more complex I suggest you disable file uploads and use the excellent class.upload.php by Colin Verot.

Disabling upload processing will still let you use Formr to build your input fields, it just won't upload and process the files. To stop Formr from uploading your files, just set the uploads property to FALSE.

$form->uploads = FALSE;

Security Check

In the following example, let's assume we don't want our visitors uploading PDF or Word documents; only photos. So let's perform a security check and make sure only images are being uploaded. We can easily do this with the $upload_accepted_mimes property, which will check the mime type of the uploaded file and make sure it's either a GIF, JPG, or PNG file.

$form->upload_accepted_mimes = 'images';

We can also specify our mime types individually...

$form->upload_accepted_mimes = 'image/jpg,image/jpeg,image/gif,image/png';

Define the Upload Directory

This next step is to tell Formr where we want to upload our files, which we do with the $upload_dir property.

$form->upload_dir = '/srv/www/uploads';

Rename the Upload

Let's go ahead and rename our uploaded image to the current time of day with the $upload_rename property.

$form->upload_rename = 'timestamp';

Create a Thumbnail

More often than not we want to show a smaller version of the uploaded image on a preview page, or as an avatar. This is easily accomplished using the $upload_resize property, where we can specify the width and height of the thumbnail, prepend a string onto the filename, specify where it should be saved, plus the amount of compression that should be used when saving.

The following will generate a 100px x 100px image, prepend the filename with tn_, save it into the uploads directory, and use 90% compression when saving.

Example

php $form->upload_resize = [ 'tn' => '100,100,tn_,/srv/www/uploads,90' ];

Produces something like

tn_1603725041.jpg

Full Upload Example

A Complete Upload Example

<?php
require 'Formr/class.formr.php';

// instantiate Formr
$form = new Formr\Formr();

// only allow images to be uploaded
$form->upload_accepted_mimes = 'images';

// define our upload directory
$form->upload_dir = '/srv/www/uploads';

// rename our upload with a 32-character hash
$form->upload_rename = 'hash';

// create a thumbnail
$form->upload_resize = [
  'thumbnail' => '100,100,tn_,' . $form->upload_dir . ',90',
];

// check if the form has been submitted
if ($form->submitted()) {
  // process the upload and put it into an array
  $file = $form->post('file');

  // printr() the array to see its keys/values
  $form->printr($file);
}
?>

<div class="container">
  <?php
    // always print Formr's messages!
    $form->messages();

    // open our form element
    $form->open_multipart();

    // add our file element
    $form->file('file');

    // submit button
    $form->submit_button();

    //close the form
    $form->close();
  ?>
</div>