Programmer's Reference Guide

Zend_File
Programmierer Referenzhandbuch

Filters for Zend_File_Transfer

Zend_File_Transfer is delivered with several file related filters which can be used to automate several tasks which are often done on files. Note that file filters are applied after validation. Also file filters behave slightly different that other filters. They will always return the file name and not the changed content (which would be a bad idea when working on 1GB files). All filters which are provided with Zend_File_Transfer can be found in the Zend_Filter component and are named Zend_Filter_File_*. The following filters are actually available:

Rename: This filter can rename files, change the location and even force overwriting of existing files.

Using filters with `Zend_File_Transfer`

The usage of filters is quite simple. There are several methods for adding and manipulating filters.

addFilter($filter, $options = null, $files = null): Adds the given filter to the filter stack (optionally only to the file(s) specified). $filter may be either an actual filter instance, or a short name specifying the filter type (e.g., 'Rename').
addFilters(array $filters, $files = null): Adds the given filters to the stack of filters. Each entry may be either a filter type/options pair, or an array with the key 'filter' specifying the filter (all other options will be considered filter options for instantiation).
setFilters(array $filters, $files = null): Overwrites any existing filters with the filters specified. The filters should follow the syntax for addFilters().
hasFilter($name): Indicates if a filter has been registered.
getFilter($name): Returns a previously registered filter.
getFilters($files = null): Returns registered filters; if $files is passed, returns filters for that particular file or set of files.
removeFilter($name): Removes a previously registered filter.
clearFilters(): Clears all registered filters.

Beispiel #1 Add filters to a file transfer

$upload = new Zend_File_Transfer();

// Set a new destination path
$upload->addFilter('Rename', 'C:\picture\uploads');

// Set a new destination path and overwrites existing files
$upload->addFilter('Size', array('C:\picture\uploads', true));

Beispiel #2 Limit filters to single files

addFilter(), addFilters(), and setFilters() each accept a final $files argument. This argument can be used to specify a particular file or array of files on which to set the given filter.

$upload = new Zend_File_Transfer();

// Set a new destination path and limits it only to 'file2'
$upload->addFilter('Rename', 'C:\picture\uploads', 'file2');

Generally you should simply use the addFilters() method, which can be called multiple times.

Beispiel #3 Add multiple filters

Often it's simpler just to call addFilter() multiple times. One call for each filter. This also increases the readability and makes your code more maintainable. As all methods provide a fluent interface you can couple the calls as shown below:

$upload = new Zend_File_Transfer();

// Set a filesize with 20000 bytes
$upload->addFilter('Rename', 'C:\picture\newjpg', 'file1')
       ->addFilter('Rename', 'C:\picture\newgif', 'file2');

Hinweis: Note that even though setting the same filter multiple times is allowed, doing so can lead to issues when using different options for the same filter.

Rename filter

The Rename filter allows to change the destination of the upload, the filename and also to overwrite existing files. It supports the following options:

oldfile: The name and destination of the old file which shall be renamed.

This option can be a string or a array. Depending on the given options the behaviour of this option will change.
newfile: The new directory, or filename of the file.

This option is optional and can be a string, a array or a boolean. Depending on the given options the behaviour of this option will change.
overwrite: Sets if the old file overwrites the new one if it already exists.

This option is optional and must be a boolean. The default value is false.

Additionally you can also use the method setFile() to set files, which erases all previous set, addFile() to add a new file to existing ones, and getFile() to get all actually set files. To simplify things, this filter understands several notations and that methods and constructor understand the same notations.

Beispiel #4 Using the Rename filter

$upload = new Zend_File_Transfer_Adapter_Http();

// Set a new destination path for all files
$upload->addFilter('Rename', 'C:\mypics\new');

// Set a new destination path only for uploadfile1
$upload->addFilter('Rename', 'uploadfile1', 'C:\mypics\newgifs');

You can use different notations. Below is a table where you will find a description and the intention for the supported notations. Note that when you use the Adapter or the Form Element you will not be able to use all described notations.

**Different notations of the rename filer and their meaning**
notation	description
addFile('C:\uploads')	Specifies a new location for all files when the given string is a directory. Note that you will get an exception when the file already exists, see the overwriting parameter.
addFile('C:\uploads\file.ext')	Specifies a new location and filename for all files when the given string is not detected as directory. Note that you will get an exception when the file already exists, see the overwriting parameter.
addFile('C:\uploads\file.ext', true)	Specifies a new location and filename for all files when the given string is not detected as directory and overwrites and existing file with the same target name. Note, that you will get no notification that a file was overwritten.
addFile('C:\temp\uploads', 'C:\uploads')	Specifies a new location for all files in the old location when the given strings are detected as directory. Note that you will get an exception when the file already exists, see the overwriting parameter.
addFile('C:\temp\uploads', 'C:\uploads', true)	Specifies a new location for all files in the old location when the given strings are detected as directory and overwrites and existing file with the same target name. Note, that you will get no notification that a file was overwritten.
addFile(array('C:\temp\uploads\file1.gif' => 'C:\uploads\file.gif'))	Specifies new locations for given files. You must always give a key-value pair of source and targetfile. Note that you will get an exception when the file already exists, see the overwriting parameter.
addFile(array('C:\temp\uploads\file1.gif' => 'C:\uploads\file.gif'), true)	Specifies new locations for given files. You must always give a key-value pair of source and targetfile and overwrites and existing file with the same target name. Note, that you will get no notification that a file was overwritten. Optionally you can give one directory with the key 0 which will then be used for all files where no source is defined.