Zend Framework: Documentation

Zend_File_Transfer enables developers to take control over file uploads and also over file downloads. It allows you to use built in validators for file purposes and gives you the ability even to change files with filters. Zend_File_Transfer works with adapters which allow to use the same API for different transport protocols like HTTP, FTP, WEBDAV and more.

	Limitation
	The current implementation of `Zend_File_Transfer` shipped in 1.6.0 is limited to HTTP Post Uploads. Download of files and other Adapters will be added in the next releases. Not implemented methods will throw an exception. So actually you should use an instance of `Zend_File_Transfer_Adapter_Http` directly. This will change in future, as soon as there are multiple adapters available.

	Forms
	When you are using `Zend_Form` you should read and use the examples described in the chapter of `Zend_Form` and not use `Zend_File_Transfer` manually. But the information you can read in this chapter will be helpful, even if you do not use it directly. All assumptions, descriptions and solutions are the same when you are using `Zend_File_Transfer` through `Zend_Form`.

The usage of Zend_File_Transfer is quite simple. It consist of two parts. The HTTP Form which does the upload, and the handling of the uploaded files with Zend_File_Transfer. See the following example:

Example 19.1. Simple File-Upload Form

This example illustrates a basic file upload which uses Zend_File_Transfer. The first part is the file form. In our example there is one file which we want to upload.


<form enctype="multipart/form-data" action="/file/upload" method="POST">
    <input type="hidden" name="MAX_FILE_SIZE" value="100000" />
        Choose a file to upload: <input name="uploadedfile" type="file" />
    <br />
    <input type="submit" value="Upload File" />
</form>

Note that you should use Zend_Form_Element_File for your convenience instead of creating the HTML manually.

The next step is to create the receiver of the upload. In our example the receiver is /file/upload. So next we will create the controller file with the action upload.


$adapter = new Zend_File_Transfer_Adapter_Http();

$adapter->setDestination('C:\temp');

if (!$adapter->receive()) {
    $messages = $adapter->getMessages();
    echo implode("\n", $messages);
}

As you see the simplest usage is to define a destination with the setDestination method and to call the receive() method. If there are any upload errors then you will get them within an exception returned.

	Attention
	Keep in mind that this is just the simplest usage. You should never just use this example as is in an living environment as it causes severe security issues. You should always use validators to increase security.

19.1.1. Supported adapters for Zend_File_Transfer

Zend_File_Transfer is build to support different adapters and also directions. It is designed to allow uploading, downloading and even forwarding (upload one adapter and download with another adapter at the same time) of files. But with Zend Framework 1.6 there is only one adapter available, the Http adapter.

Because there is only one adapter available at this time, the base class is not ready for use. So if you want to use Zend_File_Transfer you will have to use the adapter directly.

19.1.2. Options for Zend_File_Transfer

Zend_File_Transfer and their adapters support different options. You can set all options either by giving them in the constructor, or by usage of setOptions($options). getOptions() will return you the actually set options. Attached you will find a listing of all supported options.

ignoreNoFile: If this option is set to true, all validators will ignore if the file has not been uploaded by the form. This option defaults to false which throws an error of the file was not given.

19.1.3. Checking files

Zend_File_Transfer has several method which check for different assumptions which are useful when you have to process files after they have been uploaded.

isValid($files = null): This method will check if the given files are valid, based on the validators which are attached to this files. When no files are given, all files will be checked. Note that this method will be called at latest when the files are received.
isUploaded($files = null): This method will check if the given files have been uploaded by the user. This is useful when you have defined several files to be uploaded optionally. When no files are given, all files will be checked.
isReceived($files = null): This method will check if the given files have already been received. When no files are given, all files will be checked.

Example 19.2. Checking files


$upload = new Zend_File_Transfer();

// Returns all known internal file informations
$files = $upload->getFileInfo();

foreach ($files as $file => $info) {
    // file uploaded ?
    if (!$upload->isUploaded($file)) {
        print "Why havn't you uploaded the file ?";
        continue;
    }

    // validators are ok ?
    if (!$upload->isValid($file)) {
        print "Sorry but $file is not what we wanted";
        continue;
    }
}

$upload->receive();

19.1.4. Additional file informations

Zend_File_Transfer can return several additional informations on files. The following methods are available:

getFileName($file = null, $path = true): This method will return the real filename of an transferred file.
getFileInfo($file = null): This method will return all internal informations for the given transferred file.
getHash($hash = 'crc32', $files = null): This method will return a hash of the content for a given transferred file.

getFileName() accepts the name of the element as first parameter. If no name is given, all known filenames will be returned in an array. If the file is an multifile, you will also get an array. If there is only a single file a string will be returned.

Per default filenames will be returned with their complete path. If you need only the filename without path, you can set the second parameter $path which will truncate the filepath when set to false.

Example 19.3. Getting the filename


$upload = new Zend_File_Transfer();
$upload->receive();

// Returns the file names from all files
$names = $upload->getFileName();

// Returns the file names from the 'foo' form element
$names = $upload->getFileName('foo');

	Note
	Note that the filename can change when you receive the file. This is due to the fact that after receiving all filters will be applied. So you should call `getFileName()` always after you have received the files.

getHash() accepts the name of a hash algorithm as first parameter. For a list of known algorithm look into PHP's hash_algos method. If you give no algorithm, the crc32 will be used as default algorithm.

Example 19.4. Getting the hash of a file


$upload = new Zend_File_Transfer();
$upload->receive();

// Returns the hashes from all files as array if more than one file was uploaded
$hash = $upload->getHash('md5');

// Returns the hash for the 'foo' form element
$names = $upload->getHash('crc32', 'foo');

	Note
	Note that if the given file or formname contains more than one single file, the returned value will be an array.

Prev		Next
18.8. Custom Feed and Entry Classes	Home	19.2. Validators for Zend_File_Transfer

ZF Zend Framework

Programmer's Reference Guide

Chapter 19. Zend_File

19.1. Zend_File_Transfer

19.1.1. Supported adapters for Zend_File_Transfer

19.1.2. Options for Zend_File_Transfer

19.1.3. Checking files

19.1.4. Additional file informations

Search the Manual

Components

Languages Available

Translation Status Reports