README

一个轻量级的PHP文件操作库，包括创建临时文件、文件操作和元数据处理，使用SPL进行。

安装

您可以通过 Composer 安装此库。确保您的项目满足最低PHP版本要求7.4。

composer require phpdevcommunity/php-filesystem

要求

• PHP版本7.4或更高

目录

1. TempFile
2. FileInfo
3. FileSynchronizer
4. FileExplorer
5. FileSplitter

TempFile

TempFile 类提供了从base64数据、二进制数据和资源创建临时文件的方法。

fromBase64

从base64编码的数据创建临时文件。

$base64Data = '...';
$tempFile = TempFile::fromBase64($base64Data);

fromBinary

从二进制数据创建临时文件。

$binaryData = '...';
$tempFile = TempFile::fromBinary($binaryData);

fromResource

从一个资源创建临时文件。

$binaryData = '...';
$tempFile = TempFile::fromBinary($binaryData);

FileInfo

本指南介绍了如何使用 FileInfo 类在PHP中管理文件。该 FileInfo 类允许处理文件元数据，将文件转换为各种格式（base64、二进制、数据URL），以及执行文件操作，如比较和删除。

1. 实例化 FileInfo 类

要创建 FileInfo 的新实例，请将文件的路径传递给其构造函数。

$filePath = '/path/to/your/file.txt';
$fileInfo = new FileInfo($filePath);

如果文件不存在或提供的路径无效，将抛出异常。

2. 获取基本文件信息

一旦有了 FileInfo 的实例，您可以检索有关文件的详细信息

• 获取文件名:

  $filename = $fileInfo->getFilename();
  echo "Filename: $filename"; // Outputs: file.txt

• 获取真实路径:

  $realPath = $fileInfo->getRealPath();
  echo "Real Path: $realPath"; // Outputs: /absolute/path/to/file.txt

• 获取文件大小:

  $size = $fileInfo->getSize();
  echo "File Size: $size bytes";

• 获取MIME类型:

  $mimeType = $fileInfo->getMimeType();
  echo "MIME Type: $mimeType"; // Example: text/plain

• 获取文件扩展名:

  $extension = $fileInfo->getExtension();
  echo "File Extension: $extension"; // Example: txt

3. 读取和转换文件内容

您可以轻松地将文件的内容转换为不同的格式以进行存储或传输

• 转换为Base64:

  $base64 = $fileInfo->toBase64();
  echo "Base64 Encoded: $base64";

• 转换为数据URL:

  $dataUrl = $fileInfo->toDataUrl();
  echo "Data URL: $dataUrl";

• 获取文件内容为二进制:

  $binaryData = $fileInfo->toBinary();
  echo "Binary Data: $binaryData";

4. 处理文件元数据

检索有关文件的详细元数据

$metadata = $fileInfo->getMetadata();
print_r($metadata);

/* Example Output:
[
    'path' => '/absolute/path/to/file.txt',
    'size' => 1024,  // size in bytes
    'mime_type' => 'text/plain',
    'extension' => 'txt',
    'basename' => 'file.txt',
    'last_modified' => '2024-09-18 12:34:56',
    'creation_date' => '2024-09-17 10:00:00'
]
*/

5. 比较文件

您可以通过其SHA-256哈希值比较两个文件的内容

$fileInfo1 = new FileInfo('/path/to/file1.txt');
$fileInfo2 = new FileInfo('/path/to/file2.txt');

if ($fileInfo1->compareWith($fileInfo2)) {
    echo "Files are identical";
} else {
    echo "Files are different";
}

6. 文件删除

要删除与 FileInfo 对象关联的文件

if ($fileInfo->delete()) {
    echo "File deleted successfully";
} else {
    echo "Failed to delete the file";
}

一旦调用 delete 方法，文件将永久从文件系统中删除。

7. 打开文件进行读取或写入

您可以使用 SplFileObject 打开文件进行读取或写入操作

$fileObject = $fileInfo->openFile('r');
while (!$fileObject->eof()) {
    echo $fileObject->fgets();
}

8. 错误处理

如果提供的文件路径无效或文件不存在，构造函数将抛出 RuntimeException。始终在实例化 FileInfo 类之前验证文件路径

try {
    $fileInfo = new FileInfo('/path/to/invalid/file.txt');
} catch (\RuntimeException $e) {
    echo "Error: " . $e->getMessage();
}

FileSynchronizer

FileSynchronizer 类提供了一种简单的方法来在两个目录之间同步文件，具有可选的递归行为。它从源目录复制文件到目标目录，确保只有在文件缺失或已更新时才复制文件。

1. 实例化 FileSynchronizer 类

要初始化 FileSynchronizer，您需要提供源目录、目标目录以及可选的日志函数以跟踪操作。

$sourceDir = '/path/to/source';
$targetDir = '/path/to/target';
$synchronizer = new FileSynchronizer($sourceDir, $targetDir, function(array $info) {
    echo sprintf("Action: %s, Source: %s, Target: %s\n", $info['action'], $info['source'], $info['target']);
});

源和目标都必须是有效的目录，否则构造函数将抛出 InvalidArgumentException。

2. 同步文件

初始化完成后，您可以使用 sync() 方法从源目录同步到目标目录。如果想要递归同步（即包括子目录），将 recursive 参数设置为 true。

$synchronizer->sync(true); // Recursive sync
$synchronizer->sync(false); // Non-recursive sync

在同步过程中，它会复制源目录中目标目录中缺失或过时的任何文件。

3. 记录操作

您可以将自定义日志函数传递以跟踪同步操作，如复制文件。日志函数接收一个包含动作（copy）、源文件路径和目标文件路径的信息数组。

$log = function(array $info) {
    echo sprintf(
        "Action: %s\nSource: %s\nTarget: %s\n",
        $info['action'],
        $info['source'],
        $info['target']
    );
};

$synchronizer = new FileSynchronizer($sourceDir, $targetDir, $log);
$synchronizer->sync(true);

如果没有提供日志函数，同步过程将不会记录任何详细信息。

4. 处理目录

• 递归同步：如果您选择递归同步，FileSynchronizer 将复制整个目录结构，确保所有子目录和文件都被复制到目标目录中。
• 非递归同步：当将 recursive 标志设置为 false 时，只有源目录根目录中的文件会被复制到目标目录，忽略子目录。

5. 复制文件

该类仅在以下情况下复制文件

• 文件在目标目录中不存在。
• 源文件在目标目录中的文件之后被修改。

这是一份专注于 FileExplorer 类的公开方法的文档，该文档可能对希望在其项目中使用该类的开发者有所帮助。

FileExplorer

FileExplorer 类是一个用于探索目录、列出文件和根据模式或扩展名搜索文件的实用工具。本指南将指导您如何使用其公开方法进行常见文件操作。

1. 实例化 FileExplorer 类

要开始探索目录，您首先需要使用有效的目录路径实例化 FileExplorer 类。

$directoryPath = '/path/to/directory';
$explorer = new FileExplorer($directoryPath);

注意：如果提供的路径不是一个有效的目录，构造函数将抛出 InvalidArgumentException。

2. 列出所有文件和目录：listAll()

listAll() 方法返回指定目录内的所有文件和目录。您还可以通过将 $recursive 标志设置为 true 来探索子目录。

// Non-recursive listing
$files = $explorer->listAll(false);

// Recursive listing (including subdirectories)
$files = $explorer->listAll(true);

结果是一个数组，其中每个项代表一个文件或目录。每个文件或目录都作为一个关联数组提供，包含以下键

• path：文件或目录的完整路径。
• name：文件或目录的名称。
• is_directory：布尔值，表示是否为目录。
• size：文件大小（以字节为单位）（对于目录为 null）。
• modified_time：最后修改时间戳。

示例用法

$files = $explorer->listAll(true);
foreach ($files as $file) {
    echo $file['name'] . ($file['is_directory'] ? ' (Directory)' : ' (File)') . "\n";
}

3. 根据模式搜索文件：searchByPattern()

searchByPattern() 方法允许您搜索与特定模式匹配的文件（例如，*.txt 用于文本文件）。您可以通过将 $recursive 标志设置为 true 来递归搜索。

$pattern = '*.txt'; // Example pattern to search for .txt files
$files = $explorer->searchByPattern($pattern, true); // Recursive search

此方法返回与模式匹配的文件数组。结果格式与 listAll() 中相同。

示例用法

$pattern = '*.html';
$htmlFiles = $explorer->searchByPattern($pattern, true);

foreach ($htmlFiles as $file) {
    echo $file['path'] . " - Last modified: " . $file['modified_time'] . "\n";
}

4. 根据扩展名搜索文件：searchByExtension()

searchByExtension() 方法提供了一个更简单的方式来通过扩展名搜索文件。您只需要指定扩展名，它将内部使用 searchByPattern() 方法。

// Search for all .txt files (non-recursive)
$txtFiles = $explorer->searchByExtension('txt', false);

// Search for all .html files recursively
$htmlFiles = $explorer->searchByExtension('html', true);

此方法在您需要根据扩展名快速过滤文件而不需要创建模式时特别理想。

5. 实际示例

以下是一个完整示例，演示如何使用 FileExplorer 类列出目录中的所有文件，然后搜索具有特定扩展名的文件。

// Initialize FileExplorer with the desired directory
$explorer = new FileExplorer('/path/to/directory');

// List all files and directories (non-recursive)
$allFiles = $explorer->listAll(false);
foreach ($allFiles as $file) {
    echo $file['name'] . ($file['is_directory'] ? ' (Directory)' : ' (File)') . "\n";
}

// Search for all .txt files (recursive)
$txtFiles = $explorer->searchByExtension('txt', true);
foreach ($txtFiles as $file) {
    echo "Found .txt file: " . $file['path'] . "\n";
}

// Search for files that match a pattern (recursive)
$pattern = '*.log'; // Look for all .log files
$logFiles = $explorer->searchByPattern($pattern, true);
foreach ($logFiles as $file) {
    echo "Found log file: " . $file['path'] . " - Size: " . $file['size'] . " bytes\n";
}

这是一份专注于 FileSplitter 类的公开方法的文档，适用于希望将文件分成多个部分的开发者。

FileSplitter

FileSplitter 类允许开发者将大文件分割成较小的部分，可以通过指定兆字节或千字节的大小来实现。本指南解释了如何使用其公开方法来执行文件分割操作。

1. 实例化 FileSplitter 类

要开始使用 FileSplitter，你需要使用代表要分割的文件的 FileInfo 对象来实例化它。你也可以指定一个保存分割部分的目录，但如果你不指定，分割的部分将被保存在原始文件的同一目录中。

$fileInfo = new FileInfo('/path/to/large/file.txt');
$splitter = new FileSplitter($fileInfo);

如果你想要指定一个不同的目录

$splitter = new FileSplitter($fileInfo, '/path/to/output/directory');

注意：需要 FileInfo 类来提供文件详情。请确保文件路径有效，并且文件可读。

2. 按兆字节分割文件：splitMb()

splitMb() 方法允许你根据兆字节的大小将文件分割成较小的部分。每个部分都将具有指定的大小，除非文件大小不能被均匀分割。

$files = $splitter->splitMb(1); // Split into 1 MB chunks

结果是包含 FileInfo 对象的数组，每个对象代表原始文件的一个部分。

示例用法

$splitFiles = $splitter->splitMb(5); // Split into 5 MB chunks

foreach ($splitFiles as $filePart) {
    echo "Created part: " . $filePart->getRealPath() . "\n";
}

3. 按千字节分割文件：splitKb()

如果你希望以千字节为单位指定大小，可以使用 splitKb() 方法。这与 splitMb() 类似，但以千字节为单位。

$files = $splitter->splitKb(512); // Split into 512 KB chunks

这也返回表示每个部分的 FileInfo 对象数组。

示例用法

$splitFiles = $splitter->splitKb(200); // Split into 200 KB chunks

foreach ($splitFiles as $filePart) {
    echo "Created part: " . $filePart->getRealPath() . "\n";
}

4. 通用文件分割：split()

split() 方法是 splitMb() 和 splitKb() 所依赖的核心功能。你可以直接使用此方法以字节为单位指定任何自定义大小的块。

$chunkSizeInBytes = 1048576; // 1 MB in bytes
$files = $splitter->split($chunkSizeInBytes);

像其他方法一样，它返回包含文件部分的 FileInfo 对象数组。

5. 实际示例

以下是一个完整的示例，演示了如何分割文件并随后删除这些部分。

// Initialize FileInfo and FileSplitter
$fileInfo = new FileInfo('/path/to/large/file.txt');
$splitter = new FileSplitter($fileInfo);

// Split the file into 1 MB chunks
$splitFiles = $splitter->splitMb(1);

echo "File has been split into " . count($splitFiles) . " parts.\n";

许可证

本库是开源软件，许可协议为MIT 协议。