On this page
Reference
File Filters
laminas-filter also comes with a set of classes for filtering file contents, and performing file operations such as renaming.
$_FILES
All file filter filter()
implementations support either a file path string or a $_FILES
array as the supplied argument.
When a $_FILES
array is passed in, the tmp_name
is used for the file path.
Lowercase
Laminas\Filter\File\Lowercase
can be used to convert file contents to lowercase.
Supported Options
The following set of options are supported:
encoding
: Set the encoding to use during conversion.
Basic Usage
use Laminas\Filter\File\LowerCase;
use Laminas\Http\PhpEnvironment\Request;
$request = new Request();
$files = $request->getFiles();
// i.e. $files['my-upload']['tmp_name'] === '/tmp/php5Wx0aJ'
$filter = new LowerCase();
$filter->filter($files['my-upload']);
This example converts the contents of an uploaded file to lowercase. After this
process, you can use the Rename or RenameUpload
filter to replace this file with your original file, or read directly from file.
But, don't forget, if you upload a file and send your $_FILES
array to a
filter method, the LowerCase
filter will only change the temporary file
(tmp_name
index of array), not the original file. Let's check following
example:
use Laminas\Filter\File\LowerCase;
use Laminas\Filter\File\Rename;
use Laminas\Http\PhpEnvironment\Request;
$request = new Request();
$files = $request->getFiles();
// i.e. $files['my-upload']['tmp_name'] === '/tmp/php5Wx0aJ'
$lowercaseFilter = new LowerCase();
$file = $lowercaseFilter->filter($files['userfile']);
$renameFilter = new Rename([
'target' => '/tmp/newfile.txt',
'randomize' => true,
]);
$filename = $renameFilter->filter($file['tmp_name']);
With this example, the final, stored file on the server will have the lowercased content.
If you want to use a specific encoding when converting file content, you should
specify the encoding when instantiating the LowerCase
filter, or use the
setEncoding
method to change it.
use Laminas\Filter\File\LowerCase;
use Laminas\Http\PhpEnvironment\Request;
$request = new Request();
$files = $request->getFiles();
// i.e. $files['my-upload']['tmp_name'] === '/tmp/php5Wx0aJ'
$filter = new LowerCase();
$filter->setEncoding('ISO-8859-1');
$filter->filter($files['my-upload']);
The LowerCase
filter extends from the StringToLower
filter; read the
StringToLower
documentation
for more information about encoding and its exceptions.
Rename
Laminas\Filter\File\Rename
can be used to rename a file and/or move a file to a new path.
Supported Options
The following set of options are supported:
match
(string; default:*
): File name pattern to check if this filter should be applied to the input. Read thefnmatch
documentation for more detailtarget_directory
(string; default:*
): Directory to move the file(s) to, if specified. The target directory must exist and be writable by the server process.rename_to
(string: default:*
): Change the filename to the specified value. A value of*
(The default) preserves the existing file name.overwrite
(boolean; default:false
): Shall existing files be overwritten? If the file is unable to be moved into the target path, aLaminas\Filter\Exception\RuntimeException
will be thrown.randomize
(boolean; default:false
): Shall target files have a random postfix attached? The random postfix will generated withuniqid('_')
after the file name and before the extension. For example,file.txt
might be randomized tofile_4b3403665fea6.txt
.
A list of "option sets" is also supported, where a single Rename
filter instance can be configured to match and rename files using different options based on the received filename.
for example, a list such as
[
['match' => '*.txt', 'target_directory' => '/tmp/text-files'],
['match' => '*.pdf', 'target_directory' => '/tmp/pdf-files'],
];
Usage Examples
Move all filtered files to a different directory:
// 'target' option is assumed if param is a string
$filter = new \Laminas\Filter\File\Rename(['target_directory' => '/tmp/']);
echo $filter->filter('./myfile.txt');
// File has been moved to '/tmp/myfile.txt'
Rename all filtered files to a new name:
$filter = new \Laminas\Filter\File\Rename(['rename_to' => 'newfile.txt');
echo $filter->filter('./myfile.txt');
// File has been renamed to 'newfile.txt'
Move to a new path, and randomize file names:
$filter = new \Laminas\Filter\File\Rename([
'match' => '/tmp/*.txt',
'randomize' => true,
]);
echo $filter->filter('./myfile.txt');
// File has been renamed to '/tmp/newfile_4b3403665fea6.txt'
Configure different options for several possible source files:
$filter = new \Laminas\Filter\File\Rename([
[
'match' => '*.pdf'
'target_directory' => '/pdf-files/',
'rename_to' => 'newfileA.pdf',
'overwrite' => true,
],
[
'match' => '*.txt'
'target_directory' => '/text-files/',
'rename_to' => 'newfileB.txt',
'randomize' => true,
],
]);
echo $filter->filter('fileA.txt');
// File has been renamed to '/dest1/newfileA.txt'
echo $filter->filter('fileB.txt');
// File has been renamed to '/dest2/newfileB_4b3403665fea6.txt'
RenameUpload
Laminas\Filter\File\RenameUpload
can be used to rename or move an uploaded file to a new path.
The filter will only attempt to operate on uploaded files, and will typically succeed given the following inputs:
- An array representing a single PHP file upload
- A PSR7
UploadedFileInterface
- A string representing the file path of an uploaded file
Supported Options
The following set of options are supported:
target
(string; default:*
): Target directory or full filename path.overwrite
(boolean; default:false
): Shall existing files be overwritten? If the file is unable to be moved into the target path, aLaminas\Filter\Exception\RuntimeException
will be thrown.randomize
(boolean; default:false
): Shall target files have a random postfix attached? The random postfix will be generated withuniqid('_')
after the file name and before the extension. For example,file.txt
might be randomized tofile_4b3403665fea6.txt
.use_upload_name
(boolean; default:false
): When true, this filter will use$_FILES['name']
as the target filename. Otherwise, the defaulttarget
rules and the$_FILES['tmp_name']
will be used.use_upload_extension
(boolean; default:false
): When true, the uploaded file will maintain its original extension if not specified. For example, if the uploaded file isfile.txt
and the target ismynewfile
, the upload will be renamed tomynewfile.txt
.
Using the upload Name is unsafe
Be very careful when using the use_upload_name
option. For instance,
extremely bad things could happen if you were to allow uploaded .php
files
(or other CGI files) to be moved into the DocumentRoot
.
It is generally a better idea to supply an internal filename to avoid security risks.
RenameUpload
can only operate on one file at a time.
Usage Examples
Move all filtered files to a different directory.
use Laminas\Http\PhpEnvironment\Request;
$request = new Request();
$files = $request->getFiles();
// i.e. $files['my-upload']['tmp_name'] === '/tmp/php5Wx0aJ'
// i.e. $files['my-upload']['name'] === 'myfile.txt'
$filter = new \Laminas\Filter\File\RenameUpload([
'target' => './data/uploads/',
]);
echo $filter->filter($files['my-upload']);
// File has been moved to './data/uploads/php5Wx0aJ'
// ... or retain the uploaded file name
$filter = new \Laminas\Filter\File\RenameUpload([
'target' => './data/uploads/',
'use_upload_name' => true,
]);
echo $filter->filter($files['my-upload']);
// File has been moved to './data/uploads/myfile.txt'
Rename all filtered files to a new name:
// Assuming: $_FILES['my-upload']['tmp_name'] === '/tmp/php5Wx0aJ'
$filter = new \Laminas\Filter\File\RenameUpload([
'target' => './data/uploads/newfile.txt',
]);
echo $filter->filter($_FILES['my-upload']);
// File has been renamed to './data/uploads/newfile.txt'
Move to a new path and randomize file names:
use Laminas\Http\PhpEnvironment\Request;
$request = new Request();
$files = $request->getFiles();
// i.e. $files['my-upload']['tmp_name'] === '/tmp/php5Wx0aJ'
$filter = new \Laminas\Filter\File\RenameUpload([
'target' => './data/uploads/newfile.txt',
'randomize' => true,
]);
echo $filter->filter($files['my-upload']);
// File has been renamed to './data/uploads/newfile_4b3403665fea6.txt'
Handle a PSR-7 uploaded file:
use Laminas\Filter\File\RenameUpload;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\UploadedFileInterface;
$filter = new \Laminas\Filter\File\RenameUpload([
'target' => './data/uploads/',
'randomize' => true,
]);
// @var ServerRequestInterface $request
foreach ($request->getUploadedFiles() as $uploadedFile) {
// @var UploadedFileInterface $uploadedFile
$newFilePath = $filter->filter($uploadedFile);
echo $newFilePath;
// File has been renamed to './data/uploads/newfile_4b3403665fea6.txt'
}
Uppercase
Laminas\Filter\File\Uppercase
can be used to convert file contents to uppercase.
Supported Options
The following set of options are supported:
encoding
: Set the encoding to use during conversion.
Basic Usage
use Laminas\Filter\File\UpperCase;
use Laminas\Http\PhpEnvironment\Request;
$request = new Request();
$files = $request->getFiles();
// i.e. $files['my-upload']['tmp_name'] === '/tmp/php5Wx0aJ'
$filter = new UpperCase();
$filter->filter($files['my-upload']);
See the documentation on the LowerCase
filter, above, for more information.