README

从文件名中删除所有禁止字符

你在服务器上存储用户文件吗？上传的文件将通过URL地址在应用程序中可访问吗？不想丢失原始文件名吗？

想要避免无意义的随机生成的名称吗？此包将帮助您解决问题。

安装

您可以通过composer安装此包

composer require ondrej-vrto/php-filename-sanitize

基本用法

use OndrejVrto\FilenameSanitize\FilenameSanitize;

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

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

该包试图消除哪些问题？

1. 替换特殊字符
   • 文件系统保留
   • 控制字符
   • 非打印字符 DEL，不间断空格，软连字符
   • URI保留
   • URL不安全字符
2. 减少一些连续字符（空格，下划线，破折号，点）
3. Windows保留名称
4. 小写以实现Windows/Unix互操作性
5. 最大文件名长度为255字节

示例

字符串被净化并软标签化（除了破折号，点也被使用）。

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

高级设置

创建实例

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

目录功能

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

扩展功能

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

前缀，后缀功能

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

如果净化后的文件名为空，则使用默认名称

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

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

禁用转换为小写字母

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

自定义分隔符

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

警告：更改分隔符有时会导致不期望的副作用。分隔符字符从文件名和扩展名开头和结尾处删除。

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

所有功能的组合

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

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

致谢

• Ondrej Vrťo
• 所有贡献者

许可

MIT许可（MIT）。有关更多信息，请参阅许可文件。