icewind/smb

php wrapper for smbclient and libsmbclient-php

v3.6.0 2023-08-10 13:17 UTC

README

SMB

CI codecov

PHP wrapper for smbclient and libsmbclient-php

  • 重用单个 smbclient 实例以处理多个请求
  • 不会将密码泄漏到进程列表
  • 简单的 1-on-1 映射 SMB 命令
  • 基于流的 api 以消除对临时文件的需求
  • 支持直接通过 libsmbclient-php 使用 libsmbclient

示例

连接到共享

<?php
use Icewind\SMB\ServerFactory;
use Icewind\SMB\BasicAuth;

require('vendor/autoload.php');

$serverFactory = new ServerFactory();
$auth = new BasicAuth('user', 'workgroup', 'password');
$server = $serverFactory->createServer('localhost', $auth);

$share = $server->getShare('test');

服务器工厂将根据可用性自动选择 smbclientlibsmbclient-php 后端。

使用匿名认证

$serverFactory = new ServerFactory();
$auth = new AnonymousAuth();
$server = $serverFactory->createServer('localhost', $auth);

使用 kerberos 认证

使用 kerberos 认证 SMB 服务器有两种方法

  • 使用 PHP 服务器的票据
  • 重新使用客户端发送的票据

使用服务器票据

使用服务器票据允许 Web 服务器使用现有的机器账户对 SMB 服务器进行认证。

票据需要在 PHP 进程的环境中获得。

$serverFactory = new ServerFactory();
$auth = new KerberosAuth();
$server = $serverFactory->createServer('localhost', $auth);

重新使用客户端票据

通过重新使用客户端票据,您可以创建一个单一登录设置,其中用户使用 kerberos 认证对 Web 服务进行认证。Web 服务器可以将该票据转发给 SMB 服务器,允许它代表用户操作,而无需用户输入密码。

此类系统的设置相当复杂,大致需要以下步骤

  • Web 服务器使用机器账户通过 kerberos 进行认证
  • 为 Web 服务器机器账户启用委托
  • Web 服务器配置为执行 kerberos 认证并在其环境中保存票据
  • PHP 安装了 krb5 扩展
  • 客户端使用启用了转发的票据进行认证
$serverFactory = new ServerFactory();
$auth = new KerberosAuth();
$auth->setTicket(KerberosTicket::fromEnv());
$server = $serverFactory->createServer('localhost', $auth);

上传文件

$share->put($fileToUpload, 'example.txt');

下载文件

$share->get('example.txt', $target);

列出远程服务器上的共享

$shares = $server->listShares();

foreach ($shares as $share) {
	echo $share->getName() . "\n";
}

列出文件夹内容

$content = $share->dir('test');

foreach ($content as $info) {
	echo $info->getName() . "\n";
	echo "\tsize :" . $info->getSize() . "\n";
}

使用读取流

$fh = $share->read('test.txt');
echo fread($fh, 4086);
fclose($fh);

使用写入流

$fh = $share->write('test.txt');
fwrite($fh, 'bar');
fclose($fh);

注意: write() 将截断您的文件到 0 字节。您可以使用 append() 打开可写流,将指针指向文件的末尾或创建它(如果尚不存在)(append() 仅与 libsmbclient-php 兼容)。

$fh = $share->append('test.txt');
fwrite($fh, 'bar');
fclose($fh);

使用通知

$share->notify('')->listen(function (\Icewind\SMB\Change $change) {
	echo $change->getCode() . ': ' . $change->getPath() . "\n";
});

更改网络超时

$options = new Options();
$options->setTimeout(5);
$serverFactory = new ServerFactory($options);

设置协议版本

$options = new Options();
$options->setMinProtocol(IOptions::PROTOCOL_SMB2);
$options->setMaxProtocol(IOptions::PROTOCOL_SMB3);
$serverFactory = new ServerFactory($options);

注意,设置协议版本不支持 php-smbclient 版本 1.0.1 或更低。

自定义系统集成

为了运行,smbclient 后端需要获取有关其运行系统的各种信息,例如各种二进制文件的路径或系统时区。虽然获取这些信息的默认逻辑应该适用于大多数系统,但您可以自定义此行为。

为了自定义集成,您需要提供 ITimezoneProvider 和/或 ISystem 的自定义实现,并将它们作为参数传递给 ServerFactory

测试 SMB

使用以下步骤检查库是否可以连接到您的 SMB 共享。

  1. 克隆此存储库或将其作为 zip 下载
  2. 确保已安装 composer
  3. 在存储库的根目录中运行 composer install
  4. 编辑 example.php 以设置您共享的相关参数。
  5. 运行 php example.php

如果一切正常,则共享的内容应该被输出。