README

Removes all forbidden characters from the file name

Do you store files from the user on the server? Will the uploaded file be accessible in the application via a URL address? Don't want to lose the original file name?

Want to avoid meaningless randomly generated names? This package will help you solve your problem.

Installation

You can install the package via composer:

composer require ondrej-vrto/php-filename-sanitize

Basic usage

use OndrejVrto\FilenameSanitize\FilenameSanitize;

$filename = '[file#name].jpg';

$sanitize_filename = FilenameSanitize::of($filename)->get();
// Output: file-name.jpg

What problems does the package try to eliminate?

Replace special characters
- file system reserved
- control characters
- non-printing characters DEL, NO-BREAK SPACE, SOFT HYPHEN
- URI reserved
- URL unsafe characters
Reduce some consecutive characters (spaces, undescores, dashes, dots)
Windows reserved names
Lowercase for windows/unix interoperability
Max filename length to 255 bytes

Examples

Strings are sanitized and soft slugged (in addition to dashes, dots are also used).

file-name.ext                            ->  file-name.ext
火|车..票                                 ->  火-车.票
.github                                  ->  .github
filename                                 ->  filename
.env.test                                ->  .env.test
File NaME.Zip                            ->  file-name.zip
file___name.zip                          ->  file-name.zip
file---name.zip                          ->  file-name.zip
file...name..zip                         ->  file.name.zip
file<->name":.zip:                       ->  file-name.zip
~file-{name}^.[zip]                      ->  file-name.zip
   file  name  .   zip                   ->  file-name.zip
[file~name].{jpg}                        ->  file-name.jpg
file--.--.-.--name.zip                   ->  file.name.zip
file-name|#[]&@()+,;=.zip                ->  file-name.zip
<script>alert(1);</script>               ->  script
<?php malicious_function(); ?>`rm -rf `  ->  php-malicious-function-rm-rf

Advanced settings

Create instance

// classic object
(new FilenameSanitize($filename))->get();
// or static instance
FilenameSanitize::of($filename)->get();

Directory features

FilenameSanitize::of('/some#/di[]r/file#name.jpg')
    ->withSubdirectory()
    ->get();
// Output: \some\dir\file-name.jpg

FilenameSanitize::of('/some#/di[]r/file#name.jpg')
    ->addSubdirectoryToFilename()
    ->get();
// Output: some-dir-file-name.jpg

FilenameSanitize::of('/some#/di[]r/file#name.jpg')
    ->withBaseDirectory("/base/directory")
    ->get();
// Output: \base\directory\file-name.jpg

// together
FilenameSanitize::of('/some#/di[]r/file#name.jpg')
    ->withBaseDirectory("/base/directory")
    ->addSubdirectoryToFilename()
    ->withSubdirectory()
    ->get();
// Output: \base\directory\some\dir\some-dir-file-name.jpg

Extension features

FilenameSanitize::of('file_name.jpg')
    ->withNewExtension('webp')
    ->get();
// Output: file-name.webp

FilenameSanitize::of('file_name.jpg')
    ->addActualExtensionToFilename()
    ->get();
// Output: file-name-jpg.jpg

// together
FilenameSanitize::of('file_name.jpg')
    ->addActualExtensionToFilename()
    ->withNewExtension('webp')
    ->get();
// Output: file-name-jpg.webp

Prefix, suffix features

FilenameSanitize::of('file_name.jpg')
    ->widthFilenameSuffix('suffix')
    ->widthFilenamePrefix('prefix')
    ->get();
// Output: prefix-file-name-suffix.jpg

Default name if sanitized filename is empty

FilenameSanitize::of(null)
    ->get();
// throw ValueError exception

FilenameSanitize::of(null)
    ->defaultFilename('default-file-name.jpg')
    ->get();
// Output: default-file-name.jpg

Disable conversion to lowercase letters

FilenameSanitize::of('File*NAME.Ext')
    ->disableLowerCase()
    ->get();
// Output: File-NAME.Ext

Custom separator

FilenameSanitize::of('file#name.jpg')
    ->customSeparator('_-_')
    ->get();
// Output: file_-_name.jpg

Warning: Changing the separator can sometimes lead to unwanted side effects. Individual separator characters are removed from the beginning and end of the file name and extension.

FilenameSanitize::of('file#name.ext')
    ->customSeparator('ef')
    ->get();
// Output: ileefnam.xt

A combination of all functions together

FilenameSanitize::of('foo2\bar2\file-name.jpg')
    ->addActualExtensionToFilename()
    ->withBaseDirectory('C:/foo/bar')
    ->widthFilenameSuffix('surfix')
    ->widthFilenamePrefix('prefix')
    ->addSubdirectoryToFilename()
    ->withNewExtension('webp')
    ->customSeparator('_')
    ->withSubdirectory()
    ->get();
// Output:  C:\foo\bar\foo2\bar2\prefix_foo2_bar2_file_name_surfix_jpg.webp

Testing

composer test

ondrej-vrto / php-filename-sanitize

Maintainers

Details