README

======= Filesystem

为PHP应用程序提供简单、统一的文件和目录服务API，用于以统一的方式与不同的文件系统交互。

系统需求

PHP 5.3或更高版本
PSR-0兼容的自动加载器
PHP框架独立

快速查看 ...

这是对文件系统API的快速查看，有关每个方法的更多信息，请见下文。首先，应用程序连接到文件系统。从那时起，读取、写入、列出、复制、移动等文件和文件夹操作对应用程序来说都是相同的，无论底层系统如何。除了读取方法外，每个方法都设计为提供文件或文件夹的结果。由于可能会抛出异常，建议在Try/Catch块中使用方法。

文件系统适配器接口

    // Instantiate Handler (example local) and pass it into the Filesystem Adapter

    use Molajo\Filesystem\Handler\Local;
    $handler = new Local();

    use Molajo\Filesystem\Adapter;
    $adapter = new Adapter($handler);

    $true_or_false = $adapter->exists('\file\located\here.txt');

    $metadata = $adapter->getMetadata('\file\located\here.txt');
    echo $metadata->owner;      // See complete list of metadata returned, below

    $contents_of_file = $adapter->read('\file\located\here.txt');

    $list_of_results = $adapter->getList($path, $recursive, $extension_list,
        $include_files, $include_folders, $filename_mask);

    $adapter->write($path, $data, $replace, $append, $truncate);

    $adapter->delete($path, $recursive);

    $adapter->copy($path, $target_directory, $target_name, $replace, $target_handler);

    $adapter->move($path, $target_directory, $target_name, $replace, $target_handler);

    $adapter->rename($path, $new_name);

    $adapter->changeOwner($path, $user_name, $recursive);

    $adapter->changeGroup($path, $group_id, $recursive);

    $adapter->changePermission($path, $permission, $recursive);

    $adapter->touch($path, $modification_time, $access_time, $recursive);

什么是文件系统？

文件系统为文件和文件夹操作提供通用API，包括：在文件系统中以及在文件系统之间存在的、获取元数据、读取、获取列表、写入、删除、复制、移动和重命名操作。此外，应用程序还可以执行基本系统管理任务，如更改所有者、组、权限、最后更新时间和文件的触摸日期。

类实例化

实例化特定文件系统的适配器类后，应用程序可以与该文件系统交互。

本地文件系统是默认的，不需要任何输入。其他文件系统需要特定类型的输入，如下面的《文件系统处理器》部分所述。

    use Molajo\Filesystem\Handler\Local;
    $handler = new Local();

    use Molajo\Filesystem\Adapter;
    $adapter = new Adapter($handler);

使用文件系统适配器

应用程序可以使用$adapter与文件和文件夹进行交互，如下面读取文件的示例所示。

    try {
        $results = $adapter->read('\file\located\here.txt');

    } catch (Exception $e) {
        // deal with the exception
    }

文件系统API

列出各种方法，示例、参数定义以及如何访问结果。建议在Try/Catch块中使用每个方法，因为方法可能会抛出异常。

存在

验证由$path定义的文件或文件夹是否存在，返回true或false。

    try {
        $exists = $adapter->exists($path);
    } catch (Exception $e) {
        // deal with the exception
    }

    if ($exists === true) {
			echo 'The file or folder defined in $path does exist.';
    } else {
			echo 'The file or folder defined in $path does NOT exist.';
    }

参数

$path 包含文件或文件夹的绝对路径

getMetadata

检索包含在$path中定义的文件或文件夹的元数据的对象

    try {
        $metadata = $adapter->getMetadata($path);
    } catch (Exception $e) {
        // deal with the exception
    }

    // View all object properties returned


    // Use a single element
    echo $metadata->name;

参数

$path 包含文件或文件夹的绝对路径

元数据

每种文件系统类型的可用元数据可能不同。对于本地文件系统，这是可用的元数据列表。

关于文件系统处理器的元数据：root、persistence、default_directory_permissions、default_file_permissions和read_only。

关于请求路径的元数据（无论是文件还是文件夹）：path、is_absolute、absolute_path、exists、owner、group、create_date、access_date、modified_date、is_readable、is_writable、is_executable、is_directory、is_file、is_link、type、name、parent、extension、file_name_without_extension、size和mime_type。

读取

从文件系统中读取特定的文件

    try {
        $results = $adapter->read('\file\located\here.txt');
    } catch (Exception $e) {
        // deal with the exception
    }

参数

$path 包含文件或文件夹的绝对路径

获取列表

返回一个包含给定路径中文件和文件夹的数组，可选地递归处理所有子文件夹，并可选地限制结果到指定的文件扩展名。

    $path = '\file\located\here.txt';
    $recursive = true;
    $extension_list = 'txt, pdf, doc';
    $include_files = false;
    $include_folders = false;
    $filename_mask = null;

    try {
        $results = $adapter->getList($path, $recursive, $extension_list,
            $include_files, $include_folders, $filename_mask);
    } catch (Exception $e) {
        // deal with the exception
    }

参数

$path 包含文件或文件夹的绝对路径
$recursive true（默认）或false，指示是否应处理子文件夹
$extension_list 逗号分隔的文件扩展名列表，这些扩展名是合格的
$include_files 用于排除或包含列表中的文件的真或假值
$include_folders 用于排除或包含列表中的文件夹的真或假值

写入

将数据写入给定路径中标识的文件，可选地替换现有数据，追加到已存在的数据，或截断文件中的数据，但保留空文件。

    $path = '\file\located\here.txt';
    $data = 'Write this data.';
    $replace = true;
    $append = false;
    $truncate = false;

    try {
        $results = $adapter->write($path, $data, $replace, $append, $truncate);

    } catch (Exception $e) {
        // deal with the exception
    }

参数

$path 包含文件的绝对路径
$data 要写入文件的文本内容
$replace 真或假值，表示是否覆盖现有文件
$append 真或假值，表示是否将数据追加到表中的现有数据
$truncate 真或假值，表示是否截断文件中的现有数据，留下一个空文件

删除

删除指定路径中标识的文件夹和/或文件，如果指定，递归删除子文件夹和文件。

    $path = '\example\of\a\folder';
    $recursive = true;

    try {
        $results = $adapter->delete($path, $recursive);
    } catch (Exception $e) {
        // deal with the exception
    }

参数

$path 包含文件夹或文件的绝对路径
$recursive 真或假值，表示是否删除子文件夹和文件（仅适用于文件夹）。对于包含子文件夹的文件夹，假值将抛出异常。

复制

将文件和文件夹从文件系统复制到同一文件系统或不同文件系统上的位置。

当复制单个文件时，可以使用 target_name 字段指定新的文件名。

    $path                   = '\copy\contents\from\this\folder';
    $target_directory       = '\to\this\folder';
    $target_name            = null;
    $replace            	= true;
    $target_handler = 'Backup';

    try {
        $adapter->copy($path, $target_directory, $target_name, $replace, $target_handler);
    } catch (Exception $e) {
        // deal with the exception
    }

参数

$path 包含源文件夹或文件的绝对路径
$target_directory 包含目标文件夹或文件的绝对路径
$target_name 包含在复制文件时希望使用的不同文件名
$replace 真或假值，表示如果目标文件存在，是否替换它。
$target_handler 如果复制到除当前文件系统之外的文件系统，请使用。

移动

将文件和文件夹从文件系统移动到同一文件系统或不同文件系统上的位置。

当移动单个文件时，可以使用 target_name 字段指定新的文件名。

    $path                   = '\move\contents\from\this\folder';
    $target_directory       = '\to\this\folder';
    $target_name            = null;
    $replace            	= false;
    $target_handler = 'Archive';

    try {
        $adapter->move($path, $target_directory, $target_name, $replace, $target_handler);
    } catch (Exception $e) {
        // deal with the exception
    }

参数

$path 包含源文件夹或文件的绝对路径
$target_directory 包含目标文件夹或文件的绝对路径
$target_name 包含在复制文件时希望使用的不同文件名
$replace 真或假值，表示如果目标文件存在，是否替换它。
$target_handler 如果复制到除当前文件系统之外的文件系统，请使用。

重命名

将文件或文件夹重命名为指定的值。

    $path                   = '\copy\this\folder\old_name.txt';
    $new_name               = 'new_name.txt';

    try {
        $adapter->rename($path, $new_name);
    } catch (Exception $e) {
        // deal with the exception
    }

参数

$path 包含源文件夹或文件的绝对路径
$target_name 包含用于文件名的新值

更改所有者

更改路径中标识的文件或文件夹的所有者，如果指定，递归更改所有下属文件和文件夹的所有者

    $path        = '\this\folder\';
    $user_name   = 'user';
    $recursive   = true;

    try {
        $adapter->changeOwner($path, $user_name, $recursive);
    } catch (Exception $e) {
        // deal with the exception
    }

参数

$path 包含文件夹或文件的绝对路径
$user_name 系统用户名
$recursive 真或假值，表示是否删除子文件夹和文件（仅适用于文件夹）。对于包含子文件夹的文件夹，假值将抛出异常。

更改组

更改路径中标识的文件或文件夹的组，如果指定，递归更改所有下属文件和文件夹的组

    $path        = '\this\folder\';
    $group_id    = 5;
    $recursive   = true;

    try {
        $adapter->changeGroup($path, $group_id, $recursive);
    } catch (Exception $e) {
        // deal with the exception
    }

参数

$path 包含文件夹或文件的绝对路径
$group_id 数字系统组 ID
$recursive 真或假值，表示是否删除子文件夹和文件（仅适用于文件夹）。对于包含子文件夹的文件夹，假值将抛出异常。

更改权限

更改路径中标识的文件或文件夹的权限，如果指定，递归更改所有下属文件和文件夹的权限

    $path        = '\this\folder\';
    $permission  = 0755;
    $recursive   = true;

    try {
        $adapter->changePermission($path, $permission, $recursive);
    } catch (Exception $e) {
        // deal with the exception
    }

参数

$path 包含文件夹或文件的绝对路径
$permission 系统用户名
$recursive 真或假值，表示是否删除子文件夹和文件（仅适用于文件夹）。对于包含子文件夹的文件夹，假值将抛出异常。

触摸

更新 $path 中标识的目录或文件的修改时间和访问时间。

    $path                = '\copy\this\folder\old_name.txt';
    $modification_time   = $modification_time;
    $access_time         = $access_time;
    $recursive           = false;

    try {
        $adapter->touch($path, $modification_time, $access_time, $recursive);
    } catch (Exception $e) {
        // deal with the exception
    }

参数

$path 包含源文件夹或文件的绝对路径
$modification_time 包含用于修改时间的 PHP 时间值
$access_time 包含用于访问时间的 PHP 时间值
$recursive 真或假值，表示是否递归应用于子文件夹和文件（仅适用于文件夹）

文件系统处理器

要使用文件系统，应用程序实例化 Connection 类，传递对特定文件系统适配器处理器的请求。不同类型的文件系统需要不同的输入来访问环境。例如，某些系统需要用户名和密码认证。启动属性通过 $options 数组传递到文件系统适配器处理器。

本地文件系统处理器

$options 用于为适配器处理器建立连接所需的命名对值关联数组；
$handler 文件系统的标识符。例如：本地（默认）、FTP、媒体、Dropbox 等；

FTP 文件系统处理器

本部分展示了如何将一个文件系统上的文件备份到另一个文件系统上。

    $options = array(
        'source_handler' => 'local',
        'source_path'    => '/x/y/example',
        'target_handler' => 'ftp',
        'target_path'    => '/x/y/backup',
        'archive'        => 'zip'
    );

    $adapter = new \Molajo\Filesystem\File($options);
    $data    = $adapter->backup ();

参数

$path 包含源文件夹或文件的绝对路径
$target_name 包含用于文件名的新值

媒体文件系统处理器

文件系统的创新使用

合并文件系统

您可以使用 文件系统 容易地创建一个合并的文件系统：只需实例化多个类并合并读取结果。

备份

文件系统 支持将文件和文件夹复制到另一个文件系统。结合应用程序计划任务，这是一个很好的备份计划方法。

存档

文件系统 支持将文件和文件夹移动到另一个文件系统，简化了内容存档的过程。

上传和下载

使用 Composer 从 Packagist 安装

步骤 1：在您的项目中安装 composer

    curl -s https://getcomposer.org/installer | php

步骤 2：在项目根目录中创建一个 composer.json 文件

{
    "require": {
        "Molajo/Filesystem": "1.*"
    }
}

步骤 3：通过 composer 安装

    php composer.phar install

关于

Molajo 项目已采用以下规范

语义版本控制
PSR-0 自动加载器互操作性
PSR-1 和 PSR-2
[phpDocumentor2] (https://github.com/phpDocumentor/phpDocumentor2)
[phpUnit Testing] (https://github.com/sebastianbergmann/phpunit)
[Travis 持续集成] (https://travis-ci.org/profile/Molajo)
[Packagist] (https://packagist.org.cn)

提交 pull 请求和功能

pull 请求 GitHub

功能 GitHub

作者

Amy Stephen - AmyStephen@Molajo.org - http://twitter.com/AmyStephen
请参阅此项目参与的贡献者列表。

许可协议

Molajo 文件系统 采用 MIT 许可协议 - 有关详细信息，请参阅 LICENSE 文件

鸣谢

W3C 文件 API：目录和系统 W3C 工作草案 2012 年 4 月 17 日 → 规范尽可能遵循。

molajo / filesystem

维护者

详细信息