Handling File Upload

A common non intuitive use of forms in PHP is the handling of uploaded files. Pluf is providing a set of tools to make file uploads painless, secure and very flexible.

To upload files on the server, you need to know:

where to store the files on the server;
what will be the name of the file.

Next you will learn how to create a form to handle the file upload and how to use it in your view and template.

Form to Handle the Upload

Supposing that your application name is MyApp, we are going to create the form MyApp_Form_Upload to upload a file. By convention, the forms of your applications are in the Form subfolder.

The content of the MyApp/Form/Upload.php file is:

<?php
class MyApp_Form_Upload extends Pluf_Form
{
    public function initFields($extra=array())
    {
        $this->fields['thefile'] = new Pluf_Form_Field_File(
                array('required' => true,
                      'label' => __('Select file'),
                      'move_function_params' => 
                          array('upload_path'=> '/where/to/put/the/files')
                      )
                );
    }
}

What you can see is that we use of Pluf_Form_Field_File form field. This field is specialized to handle the uploading of files. This field has the standard options like required or label, but also the specific option move_function_params.

The move_function_params is used to path parameters to the function that will copy the file from the place where it is put by PHP to where you want. Here are the possible parameters for the default function:

upload_path: The path in which the uploaded file will be stored. By default, it will use the upload_path general configuration variable and if not defined it will use the /tmp folder.
upload_path_create: If set to true, try to create the upload folder if not existing. By default it does not try to create the folder.
upload_overwrite: Set it to true if you want to allow overwritting of existing files.
file_name: Force the file name to this name and do not use the original file name. If this name contains '%s' for example 'subfolder/myid-%s', '%s' will be replaced by the original filename. This can be used when for example, you want to prefix with the id of an article all the files attached to this article.

Usage of the Form in the View/Template

Here is a basic template to handle the upload form we just created:

<html><head>
<title>Upload a File</title>
</head>
<body>
<h1>Upload a File</h1>
{if $form.errors}
    <p>
    Errors when uploading the file. Please correct them 
    to upload this file.
    </p>
   {if $form.get_top_errors}{$form.render_top_errors}{/if}
{/if}
<form method="post" enctype="multipart/form-data" action=".">
{$form.render_p}
<p>
<input type="submit" id="submit" name="submit" value="Upload this file" />
</p>
</form>
</body></html>

The template is really simple. At the top, we display errors if we have errors in the form. Then we render the form. Note the enctype value, set to multipart/form-data. This is needed when uploading files in a form. Save this file in MyApp/templates/myapp/upload.html.

Now, the code in the view is like for the standard Pluf_Form:

public function myUploadView($request, $match)
{
    if ($request->method == 'POST') {
        $form = new MyApp_Form_Upload(array_merge($request->POST, 
                                                  $request->FILES));
        if ($form->isValid()) {
            // Optional message to the authenticated user.
            // $request->user->setMessage(__('The file was uploaded successfully.'));
            $url = Pluf_HTTP_URL_urlForView('MyApp_Views::home');
            return new Pluf_HTTP_Response_Redirect($url);
        }
    } else {
        $form = new MyApp_Form_Upload();
    }
    return Pluf_Shortcuts_RenderToResponse('myapp/upload.html',
                                           array('form' => $form),
                                           $request);
}

The only difference with respect to the standard way to submit a form is that you need to add the $request->FILES array during initialization of the form in the POST case.

Now, take a look in the folder you gave as upload path in MyApp_Form_Upload and start to upload files.

Even More Control

The Pluf_Form_Field_File form field has the following parameters:

widget: The default is 'Pluf_Form_Widget_FileInput' but if you want a special widget you can create your own.
max_size: The maximum size of the uploaded file in bytes. By default this is about 2MB. Note that you cannot exceed the limit defined in PHP by itself.
move_function: The default is 'Pluf_Form_Field_File_moveToUploadFolder' you are free to create your own function if you cannot achieve what you want with the parameters of the default function.
move_function_params: If you create your own function or use the default function, you can pass parameters to the move function. By default array(). The parameters of the default move function have been described above.

Report issues in the documentation

If you find errors or issues in the documentation, report a bug. We will update the documentation accordingly.