File upload

System class waRequest offers convenient tools to manage files uploaded via the HTTP protocol (using web forms elements <input type="file">).

Uploading a single file

Suppose we have the following web form with one input element of type file:

<form action="..." method="post" enctype="multipart/form-data">
  ...
  <input type="file" name="photo">
  ...
</form>

In order to process the file uploaded through this form, use method waRequest::file() returning an instance of class waRequestFile, which will allow you to perform further operations on the uploaded file.

In fact, an instance of class waRequestFileIterator is returned, but in this case it acts as a transparent wrapper around the single instance of class waRequestFile in the file list. Read more about class waRequestFileIterator below in subsection "Uploading multiple files".

$file = waRequest::file('photo');

The fields of class waRequestFile are accessible only for reading; their meanings are completely identical to those of the $_FILES array items:

• $file->name;
• $file->type;
• $file->size;

• $file->tmp_name; this field's value can also be obtained through conversion of the $file variable to the string data type:

  $tmp_file_name = (string) $file;

• $file->error;
• $file->extension; returns the original file name extension.

Methods of class waRequestFile:

• $file->uploaded() returns true, if a file upload has occurred (i.e. if the value of the input field of type file in a web form is not empty); if a file was not uploaded (i.e. if $file->uploaded() returns false), then attempts to call all other methods of class waRequestFile will return an instance of exception object waException;
• $file->moveTo('path/to/file') moves the uploaded file to the specified directory (similarly to PHP function move_uploaded_file());
• $file->moveTo('path/to/dir', 'filename') the same as above, but a new name is assigned to the uploaded file;
• $file->copyTo('path/to/file') copies the uploaded file to the specified directory;
• $file->copyTo('path/to/dir', 'filename') the same as above, but a new name is assigned to the created file copy;
• $file->waImage() returns an instance of class waImage for image processing.

Attention! If an uploaded file is not a valid image file, attempts to call method waImage() will raise Exception. For this reason we recommend calling it inside a try/catch block as shown below:

try {
  $file->waImage()
       ->resize(...)
       ->crop(..)
       ->save(...);
} catch(Exception $e) {
    echo "The uploaded file is not a valid image file or some other error occurred: ".$e->getMessage();
    return;
}

Read more about class waImage in section "Image processing".

Uploading multiple files

Suppose you have a web form with several file uploading elements input of type file with equal names:

<form action="..." method="post" enctype="multipart/form-data">
  ...
  <input type="file" name="photo[]">
  <input type="file" name="photo[]">
  <input type="file" name="photo[]">
  ...
</form>

Method waRequest::file() returns an instance of class waRequestFileIterator:

$files = waRequest::file('photo');

Class waRequestFileIterator offers the same methods as waRequestFile. They work so as if they were applied to the first file in the list. Method $files->uploaded() determines whether at least one file has been uploaded.

Class waRequestFileIterator implements interface Iterator; it means that you can use a foreach cycle to access each uploaded file's properties. Each array item constitutes an instance of class waRequestFile, for which all the above mentioned methods are available; e.g.:

foreach($files as $file) {
    ...
}