README

关于

此轻量级库提供了一种方法，用于清理字符串以便在文件名中使用。

Web应用程序通常提示用户下载具有特定名称的文件，这些名称应遵守目标操作系统（及其关联的文件系统）的命名约定，否则可能会出现错误。

虽然可以通过浏览器元数据检测目标操作系统，但没有实际的方法可以检测目标文件系统，它是决定哪些文件命名约定适用的最终裁判者。

方便的是，大多数浏览器执行字符串替换以确保下载的文件不会违反目标操作系统的约定，但开发者不能仅仅依赖于这种能力，因为很多时候他们需要命名打包在某种存档中的文件，在这种情况下，浏览器在这方面无法提供帮助。只有在存档解包时，如果不注意预防，才可能会出现文件系统错误。

鉴于应用程序无法可靠地确定目标文件系统将执行哪些命名约定，最实际的做法是避免违反任何常用文件系统的约定。此库旨在提供这种精确的能力。

支持的操作系统和文件系统

绝大多数最终用户系统正在运行GNU/Linux、Windows或MacOS，对于不运行上述操作系统的系统，它们运行的是支持上述操作系统之一的文件系统的操作系统。因此，最实际的做法是仅清理这些操作系统禁止的字符。

额外的安全措施

有些字符虽然在文件系统级别没有被禁止，但在应用程序生成的文件名中允许这些字符可能是“危险的”。这尤其适用于从用户输入派生出来的文件名，以及在问题文件名可能被其他地方处理的场景中，尤其是当这些文件名可能被开发者无法控制的代码（第三方扩展等）处理时。在解包包含某些文件名的存档时，必须小心谨慎。

为了避免与恶意文件名相关的某些风险，此库还提供了可选方法来删除危险的字符，以及PHP代码。

安装

只需使用Composer在你的项目中要求此库

composer require indiehd/filename-sanitizer

用法示例

use IndieHD\FilenameSanitizer\FilenameSanitizer;

// Add illegal characters and a null-byte at the end of the name.

$sanitizer = new FilenameSanitizer('On / Off Again: My Journey to Stardom.jpg' . chr(0));

$sanitizer->stripIllegalFilesystemCharacters();

// The resultant string is free of the offending characters.

var_dump($sanitizer->getFilename());

// Output:
// "On  Off Again My Journey to Stardom.jpg"

提供了一些额外的函数来进一步清理文件名。这些函数可以按任意顺序链接。

$sanitizer = new FilenameSanitizer('<?php malicious_function(); ?>`rm -rf /`' . chr(0));

$sanitizer->stripPhp()
    ->stripRiskyCharacters()
    ->stripIllegalFilesystemCharacters();
    
var_dump($sanitizer->getFilename());

// Output:
// "rm -rf "

局限性

此库不努力验证给定文件名的长度，因为给定有效长度的确定可能非常困难，涉及许多因素，尤其是处理存档中的目录结构时。

例如，当文件被打包到存档中时，其文件名长度在很大程度上是不相关的，因为当存档解包时，长度限制包括当前工作目录的深度，存档本身还可以包含任意长度的任何层次结构。

即使在考虑上述内容的情况下，目标文件系统限制可能会根据用于访问文件系统的API而变化。

底线是，文件名长度必须在完整文件系统路径的上下文中考虑，这超出了此库的范围，应根据特定应用程序的业务需求进行实现。

版本控制

该库尽力遵循语义化版本控制。

贡献

欢迎提交拉取请求，并应遵循indieHD 项目文档中描述的指南。