ondrej-vrto / php-filename-sanitize
Removes all forbidden characters from the file name or path.
Fund package maintenance!
OndrejVrto
Installs: 4 136
Dependents: 2
Suggesters: 0
Security: 0
Stars: 5
Watchers: 1
Forks: 0
Open Issues: 1
Requires
- php: >=4.0.7
Requires (Dev)
- php: ^8.1
- laravel/pint: ^1.2
- pestphp/pest: ^2.26
- phpstan/phpstan: ^1.9
- rector/rector: ^1.0.4
This package is auto-updated.
Last update: 2024-10-28 15:02:23 UTC
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
Changelog
Please see CHANGELOG for more information on what has changed recently.
Credits
License
The MIT License (MIT). Please see License File for more information.