README

PHP 的面向对象 FTP 客户端。

安装

此库可以通过 Composer 安装

composer require brick/ftp

要求

此库需要 PHP 7.2 或更高版本，以及 ftp 扩展。

项目状态与发布流程

此库仍在开发中。

当前版本号格式为 0.x.y。当引入非破坏性更改（添加新方法、优化现有代码等）时，y 会递增。

当引入破坏性更改时，总是开始一个新的 0.x 版本周期。

因此，锁定项目到特定的发布周期，例如 0.1.* 是安全的。

如果您需要升级到较新的发布周期，请查看 发布历史 了解每个后续 0.x.0 版本引入的更改列表。

包内容

此仓库仅包含 3 个类，位于 Brick\Ftp 命名空间中

• FtpClient 是用于与 FTP 服务器交互的主要类
• FtpException 在任何操作失败时抛出
• FtpFileInfo 在列出目录时返回

快速入门

连接和登录

use Brick\Ftp\FtpClient;
use Brick\Ftp\FtpException;

try {
    $client = new FtpClient();

    $host    = 'ftp.example.com'; // FTP server host name
    $port    = 21;                // FTP server port
    $ssl     = false;             // whether to open a secure SSL connection
    $timeout = 90;                // timeout in seconds

    $username = 'ftp-user';
    $password = 'p@ssw0rd';

    $client->connect($host, $port, $ssl, $timeout);
    $client->login($username, $password);

    // You usually want to set passive mode (PASV) on; see below for an explanation
    $client->setPassive(true);
} catch (FtpException $e) {
    // An error occurred!
}

在 connect() 中只需主机名即可，其他值（端口、SSL、超时）是可选的，默认值如上所示。

什么是被动模式？

被动模式，也称为 PASV FTP 命令，是告诉服务器打开客户端可以连接的端口的机制，用于上传/下载文件。

默认情况下（未启用被动模式），客户端会打开一个本地端口并请求服务器连接回客户端。

这要求相关端口不被防火墙阻止，并且直接对互联网开放（没有 NAT，或使用端口转发）。在实际操作中，使用被动模式要容易得多，因为大多数 FTP 服务器已经配置为支持它。

异常处理

如您在上面所见，我们将所有对 FtpClient 方法的调用都包裹在 try-catch 块中。为了简洁，下面的示例中不会这样做，但您应该在每次调用 FtpClient 方法时捕获 FtpException，否则如果发生错误，您的应用程序将退出并显示 "未捕获的异常"。

获取工作目录

echo $client->getWorkingDirectory(); // e.g. /home/ftp-user

设置工作目录

$client->setWorkingDirectory('/home/ftp-user/archive');

列出目录

$files = $client->listDirectory('.');

foreach ($files as $file) {
    // $file is an FtpFileInfo object
    echo $file->name, PHP_EOL;
}

listDirectory() 返回的数组中的每个值都是一个 FtpFileInfo 对象。根据 FTP 服务器的功能，它可能只包含文件名，也可能包含更多信息

如果服务器不支持 MLSD 命令，则只能获取文件名。如果服务器支持此命令，则将提供更多信息；具体取决于服务器。因此，在尝试使用属性之前，您应该检查该属性是否为 null，并相应地操作。

如果可用，创建时间和最后修改时间将采用以下格式之一

• YYYYMMDDHHMMSS
• YYYYMMDDHHMMSS.sss

递归列出给定目录下的所有文件

这将遍历给定的目录及其所有子目录，并返回找到的所有文件。

就像listDirectory()一样，结果是FtpFileInfo对象的数组，但数组的键是文件相对于给定目录的路径。

$files = $client->recursivelyListFilesInDirectory('.');

foreach ($files as $path => $file) {
    echo $path, PHP_EOL; // a/b/c.txt
    echo $file->name, PHP_EOL; // c.txt
}

请注意，这取决于客户端区分文件和目录的能力。因此，如果服务器不支持MLSD命令，则结果始终为空数组。

此外，请注意，根据文件和目录的数量，此方法可能需要很长时间才能执行。

重命名文件或目录

$client->rename('old/path/to/file', 'new/path/to/file');

删除文件

$client->delete('path/to/file');

删除目录

$client->removeDirectory('path/to/directory');

目录必须是空的，否则将抛出异常。

获取文件大小

$size = $client->getSize('path/to/file'); // e.g. 123456

下载文件

$client->download($localFile, $remoteFile);

• $localFile可以是包含本地文件名的string，或者包含文件指针的resource。
• $remoteFile是FTP服务器上文件的路径。

此方法接受2个额外的可选参数

• $mode: FTP_BINARY（默认）或FTP_ASCII（以下解释）
• $resumePos: 从远程文件开始下载的位置（默认0）

FTP_BINARY或FTP_ASCII？

• FTP_BINARY以原始形式传输文件，不进行任何修改，这是默认值。
• FTP_ASCII将文件中的换行符（假设它是文本文件）转换为目标平台期望的格式。通常不应使用此模式。

上传文件

$client->upload($localFile, $remoteFile);

• $localFile可以是包含本地文件名的string，或者包含文件指针的resource。
• $remoteFile是FTP服务器上文件的存储路径

此方法接受2个额外的可选参数

• $mode: FTP_BINARY（默认）或FTP_ASCII（见以上解释）
• $startPos: 从远程文件开始上传的位置（默认0）

发送原始命令

如果出于任何原因，您需要向服务器发送原始FTP命令，此方法适用于您。结果是服务器返回的所有行的数组。

请注意，此方法不会检查服务器响应是否包含错误代码，它始终返回原始输出。

$lines = $client->sendRawCommand('FEAT');

foreach ($lines as $line) {
    echo $line, PHP_EOL;
}

示例响应

211- Extensions supported:
 AUTH TLS
 PBSZ
 PROT
 CCC
 SIZE
 MDTM
 REST STREAM
 MFMT
 TVFS
 MLST
 MLSD
 UTF8
211 End.

关闭连接

$client->close();