README

这是一个针对 php 的高层文件系统抽象，受 Java 文件系统 API 的启发。

为什么还需要另一个文件系统抽象呢？

我们评估了一些文件系统抽象框架，例如 Gaufrette。但我们找到的任何框架都不是真正的文件系统抽象。例如，Gaufrette 更像是一个 key => value 存储，它使用文件系统或在线存储作为源。一些基本功能，如删除目录，在 Gaufrette 中不可用。在文件系统适配器之间复制文件也是不可能的。

php-filesystem 的好处是它是一个独特的层，可以...

• 在处理文件时使用（包括临时文件）
• 在多个文件系统之间使用（也可以在它们之间移动或复制文件）
• 几乎完全替代了 php 文件 API
• 不隐藏 文件结构
• 向文件系统提供高、低层功能
• 与 php 迭代器一起工作
• 提供“合并”的文件系统，该系统从多个文件系统中构建一个合并的结构
• 支持流式传输
• 提供可配置的公共 URL 生成（对于 Web 应用程序很有用）

文件系统 API

Filesystem 是访问任何文件系统的基本接口。您需要一个 Filesystem 实例来连接到文件系统并获取文件，但不需要用它来工作。

File 是访问文件系统内文件和目录的基本接口。一个 File 实例代表底层文件系统中的路径名。使用 File，您可以执行所有想做的事情，创建文件和目录，删除文件和目录，读取和写入文件以及列出目录内容，包括 glob。

FS 是一个 静态 对象，用于控制和对全局文件系统访问进行访问。目前 FS 仅处理系统临时文件系统。

TemporaryFilesystem 是 Filesystem 的扩展接口。该 TemporaryFilesystem 提供了 createTempFile 和 createTempDirectory 方法。使用这些方法创建的所有文件/目录将在文件系统被销毁时被删除。

Util 是一个包含一些与文件系统相关方法的 静态 对象。

PublicUrlProvider 是一个用于生成文件公共 URL 的类的接口。

AbstractFile 是 File 的基本抽象实现。

与文件系统一起工作

获取文件系统的根 / 节点

/** @var Filesystem $fs */
/** @var File $root */
$root = $fs->getRoot();

从文件系统中获取一个文件

/** @var Filesystem $fs */
/** @var File $file */
$file = $fs->getFile('/example.txt');

测试文件是否存在以及它是否是文件、目录或链接

/** @var File $file */
if ($file->exists()) {
	if ($file->isLink()) {
		// $file is a link
	}
	if ($file->isFile()) {
		// $file is a file
	}
	if ($file->isDirectory()) {
		// $file is a directory
	}
}

获取有关文件的基本信息

/** @var File $file */
// get the passname INSIDE of the filesystem (this may not be the real pathname)
$pathname = $file->getPathname();

// get the basename
$basename = $file->getBasename();

// the the extension
$extension = $file->getExtension();

// get the parent directory
/** @var File $parent */
$parent = $file->getParent();

// get last access time
$accessTime = $file->getAccessTime();

// get creation time
$creationTime = $file->getCreationTime();

// get last modified time
$lastModified = $file->getLastModified();

// get file size
$size = $file->getSize();

// get owner (may be the name or uid)
$owner = $file->getOwner();

// get group (may be the name or gid)
$group = $file->getGroup();

获取和测试权限

/** @var File $file */
// get permissions
$mode = $file->getMode();

// test if file is readable
if ($file->isReadable()) {
	// do something...
}

// test if file is writeable
if ($file->isWriteable()) {
	// do something...
}

// test if file is executable
if ($file->isExecutable()) {
	// do something...
}

删除文件和目录

/** @var File $file */
if ($file->isDirectory()) {
	$file->delete(true); // recursive delete!!!
}
else {
	$file->delete();
}

复制文件

请注意：$source 和 $target 不需要是同一文件系统中的文件！

/** @var File $source */
/** @var File $target */
$source->copyTo($target);

重命名/移动文件

请注意：$source 和 $target 不需要是同一文件系统中的文件！

/** @var File $source */
/** @var File $target */
$source->moveTo($target);

创建一个目录

/** @var File $file */
if (!$file->exists()) {
	$file->mkdir();
}

创建一个目录路径（包括所有缺失的父目录）

/** @var File $file */
if (!$file->exists()) {
	$file->mkdirs();
}

创建一个新的空文件

/** @var File $file */
if (!$file->exists()) {
	$file->createNewFile();
}

读取和写入文件

/** @var File $file */
// read the file
$content = $file->getContents();

// write to the file
$file->setContents("Hello world!\n");

// append to the file
$file->appendContents("The world is like a pizza!\n");

截断文件

/** @var File $file */
$file->truncate(1024); // truncate to 1024 bytes

流式传输文件

/** @var File $file */
// read the file
$stream = $file->openStream('rb');
$content = stream_get_contents($stream);
fclose($stream);

// write to the file
$stream = $file->openStream('wb');
fwrite($stream, "Hello world!\n");
fclose($stream);

// append to the file
$stream = $file->openStream('ab');
fwrite($stream, "The world is like a pizza!\n");
fclose($stream);

计算文件哈希值

/** @var File $file */
// get md5 hash
$md5 = $file->hashMD5();

// get raw md5 hash
$md5raw = $file->hashMD5(true);

// get sha1 hash
$sha1 = $file->hashSHA1();

// get raw sha1 hash
$sha1raw = $file->hashSHA1(true);

列出目录中的文件

/** @var File $file */
if ($file->isDirectory()) {
	// get files and directories
	$children = $file->listAll();

	// get files only
	$files = $file->ls();

	// get directories only
	$directories = $file->listDirectories();
}

在目录中 glob 文件

/** @var File $file */
if ($file->isDirectory()) {
	// get files and directories
	$children = $file->glob('*example*');

	// get files only
	$files = $file->globFiles('*example*');

	// get directories only
	$directories = $file->globDirectories('*example*');
}

迭代目录（简单）

请注意：魔法子节点 . 和 .. 永远不会对您可见！

/** @var File $file */
if ($file->isDirectory()) {
	/** @var File $child */
	foreach ($file as $child) {
		// do somethink with $child
	}
}

迭代目录（专家）

请注意：魔法子节点 . 和 .. 永远不会对您可见！

use Bit3\Filesystem\Iterator\FilesystemIterator;

/** @var File $file */
if ($file->isDirectory()) {
	$iterator = new FilesystemIterator($file, FilesystemIterator::CURRENT_AS_PATHNAME);

	/** @var string $child */
	foreach ($file as $child) {
		// $child will be the pathname
	}
}

获取文件的实际 URL

/** @var File $file */
$url = $file->getRealUrl();
// -> file:/real/path/to/file
// or
// -> ftp://username:password@host:port/path/to/file
// or
// ...

获取文件的公共 URL

/** @var File $file */
$url = $file->getPublicUrl();
// may return false|null if no public url is available
if ($url) {
	header('Location: ' . $url);
}

支持的文件系统

本地文件系统

允许访问本地文件系统。

use Bit3\Filesystem\Local\LocalFilesystem;
use Bit3\Filesystem\Iterator\RecursiveFilesystemIterator;
use RecursiveTreeIterator;

// access the filesystem
$fs = new LocalFilesystem('/path/to/directory');

// create a filesystem iterator
$filesystemIterator = new RecursiveFilesystemIterator($root, FilesystemIterator::CURRENT_AS_BASENAME);

// create a tree iterator
$treeIterator = new RecursiveTreeIterator($filesystemIterator);

// output the filesystem tree
foreach ($treeIterator as $path) {
	echo $path . "\n";
}

LocalFilesystem 构造函数接受一个指向根目录的 基础路径 和一个可选的 PublicUrlProvider 作为第二个参数。来自 LocalFilesystem 的所有文件相对于 基础路径，即使是绝对文件。

合并文件系统

合并文件系统类似于 联合挂载。使用合并文件系统，可以将多个其他文件系统挂载到一个虚拟结构中。

use Bit3\Filesystem\Merged\MergedFilesystem;
use Bit3\Filesystem\Local\LocalFilesystem;
use Bit3\Filesystem\Iterator\RecursiveFilesystemIterator;
use RecursiveTreeIterator;

// create a merged filesystem
$fs = new MergedFilesystem();

// mount some other filesystems into the structure
$fs->mount('/home', new LocalFilesystem('/path/to/directory'));
$fs->mount('/remote/server', new LocalFilesystem('/other/path'));
$fs->mount('/tmp', new LocalTemporaryFilesystem('/tmp'));

// create a filesystem iterator
$filesystemIterator = new RecursiveFilesystemIterator($root, FilesystemIterator::CURRENT_AS_BASENAME);

// create a tree iterator
$treeIterator = new RecursiveTreeIterator($filesystemIterator);

// output the filesystem tree
foreach ($treeIterator as $path) {
	echo $path . "\n";
}

MergedFilesystem 构造函数接受一个可选的文件系统对象作为根 (/) 文件系统。

FTP 文件系统

FTPFilesystem 允许访问 FTP 服务器。

use Bit3\Filesystem\FTP\FTPFilesystemConfig;
use Bit3\Filesystem\FTP\FTPFilesystem;
use Bit3\Filesystem\Iterator\RecursiveFilesystemIterator;
use RecursiveTreeIterator;

// create a ftp configuration
$config = new FTPFilesystemConfig('example.com');
$config->setPassiveMode(true);
$config->setUsername('user');
$config->setPassword('password');
$config->setPath('/path/on/the/ftp');

// access the filesystem
$fs = new FTPFilesystem($config);

// create a filesystem iterator
$filesystemIterator = new RecursiveFilesystemIterator($root, FilesystemIterator::CURRENT_AS_BASENAME);

// create a tree iterator
$treeIterator = new RecursiveTreeIterator($filesystemIterator);

// output the filesystem tree
foreach ($treeIterator as $path) {
	echo $path . "\n";
}

FTPFilesystem 构造函数接受一个 FTPFilesystemConfig 实例和一个可选的 PublicUrlProvider 作为第二个参数。使用 FTPFilesystemConfig 对象来设置 FTP 配置。该实例可以用于多个 FTPFilesystem 实例化。

SSH 文件系统

正在进行中...