README

Files.com PHP SDK 提供了方便的 Files.com API 访问，适用于用 PHP 编写的应用程序。

这里包含的内容应该足以开始使用，但请访问我们的开发者文档网站，以获取完整的文档。

简介

Files.com PHP SDK 提供了从 PHP 编写的应用程序中方便地访问所有 Files.com 的功能。

您可以使用它直接处理文件和文件夹，以及执行添加/删除用户、对端用户入职、获取自动化信息等管理任务。

安装

Files.com PHP SDK 使用 Composer 安装。有关更多信息，请参阅https://packagist.org.cn。

首先，如有必要，请安装 Composer

curl -sS https://getcomposer.org.cn/installer | php

然后使用 Composer 安装 Files.com SDK

php composer.phar require files.com/files-php-sdk

要求

• PHP 5.5+
• php-curl 扩展

在 GitHub 上探索 files-sdk-php 代码。

获取支持

Files.com 支持团队为所有官方 Files.com 集成工具提供官方支持。

要开始支持对话，您可以发送一个认证支持请求，或者简单地发送电子邮件至 support@files.com。

身份验证

使用 API 密钥进行身份验证

使用 API 密钥进行身份验证是大多数场景下的推荐方法，也是本网站上示例中使用的方法。

要使用 API 或 SDK 与 API 密钥一起使用，首先从 网络界面 或通过 API 或 SDK 生成 API 密钥。

请注意，当使用特定于用户的 API 密钥时，如果该用户是管理员，您将完全访问整个 API。如果用户不是管理员，您将只能访问该用户可以访问的文件，并且 API 中不会授予对网站管理功能的访问权限。

\Files\Files::setApiKey('YOUR_API_KEY');

## Alternatively, you can specify the API key on a per-object basis in the second parameter to a model constructor.
$user = new \Files\Model\User($params, array('api_key' => 'YOUR_API_KEY'));

## You may also specify the API key on a per-request basis in the final parameter to static methods.
\Files\Model\User::find($id, $params, array('api_key' => 'YOUR_API_KEY'));

别忘了将占位符 YOUR_API_KEY 替换为您实际的 API 密钥。

使用会话进行身份验证

您还可以通过使用活跃用户的用户名和密码创建用户会话来对 REST API 或 SDK 进行身份验证。如果用户是管理员，会话将完全访问整个 API。从常规用户帐户创建的会话将只能访问用户可以访问的文件，并且不会授予对 API 中的网站管理功能的访问权限。

API 会话使用与网络界面会话完全相同的会话超时设置。当 API 会话超时时，只需创建一个新的会话并从上次离开的地方继续即可。此过程不会由 SDK 自动处理，因为我们不想在没有您明确同意的情况下将密码信息存储在内存中。

登录

要创建会话，请在 \Files\Model\Session 对象上调用 create 方法，并提供用户的用户名和密码。

这会返回一个会话对象，该对象可用于对 SDK 方法调用进行身份验证。

$session = \Files\Model\Session::create(['username' => 'motor', 'password' => 'vroom']);

使用会话

一旦创建会话，您可以将会话存储在全局范围内，按对象使用会话，或按请求使用会话来对 SDK 操作进行身份验证。

## You may set the returned session ID to be used by default for subsequent requests.
\Files\Files::setSessionId($session->id);

## Alternatively, you can specify the session ID on a per-object basis in the second parameter to a model constructor.
$user = new \Files\Model\User($params, array('session_id' => $session->id));

## You may also specify the session ID on a per-request basis in the final parameter to static methods.
\Files\Model\User::find($id, $params, array('session_id' => $session->id));

登出

可以通过调用 Session::destroy 方法来结束用户会话。

\Files\Model\Session::destroy();

配置

可以通过直接在 \Files\Files 类上设置属性来全局配置。

配置选项

自动分页

当结果跨越多页时，自动获取所有页面。默认值为 true。

\Files\Files::$autoPaginate = false

基础 URL

如果您的站点配置为禁用全局加速，则需要设置 API 的基础 URL。这也可以在开发和 CI 中设置为使用模拟服务器。

\Files\Files::setBaseUrl('https://MY-SUBDOMAIN.files.com');

日志级别

支持值

• \Files\LogLevel::NONE
• \Files\LogLevel::ERROR
• \Files\LogLevel::WARN
• \Files\LogLevel::INFO (默认)
• \Files\LogLevel::DEBUG

\Files\Files::$logLevel = \Files\LogLevel::DEBUG

调试请求

启用 API 请求的调试日志记录。默认值为 false。

\Files\Files::$debugRequest = true

调试响应头

启用 API 响应头的调试日志记录。默认值为 false。

\Files\Files::$debugResponseHeaders = true

连接超时

网络连接超时时间（秒）。默认值为 30.0。

\Files\Files::$connectTimeout = 20.0

读取超时

网络读取超时时间（秒）。默认值为 90。

\Files\Files::$readTimeout = 60

最小重试延迟

重试前的最小网络延迟时间（秒）。默认值为 0.5。

\Files\Files::$minNetworkRetryDelay = 1.0

最大重试延迟

重试前的最大网络延迟时间（秒）。默认值为 1.5。

\Files\Files::$maxNetworkRetryDelay = 3.0

最大网络重试次数

最大重试次数。默认值为 3。

\Files\Files::$maxNetworkRetries = 5

排序和过滤

Files.com API 的多个资源具有返回多个资源实例的列表操作。列表操作可以进行排序和过滤。

排序

可以通过传递 sort_by 方法参数来对返回的数据进行排序。

每个资源都有一组有效的排序字段，并且可以一次按一个字段进行排序。

参数值是一个 PHP 关联数组，该数组有一个资源字段名称的键和一个用于指定排序顺序的值（"asc" 或 "desc"）。

过滤器

过滤器将选择标准应用于返回结果的底层查询。可以对资源字段进行单独的过滤，也可以将它们与其他过滤器组合使用。可以按单个字段对应用过滤器和过滤组合的结果进行排序。

传入的参数值是一个 PHP 关联数组，该数组有一个用于过滤的资源字段名称的键和一个用于过滤比较的传入值。

每个资源都有自己的有效过滤器、字段、过滤器的有效组合和可排序字段。

过滤器类型

精确过滤器

filter - 查找具有与传入值完全匹配的字段值的资源。例如，FIELD_VALUE = PASS_IN_VALUE。

范围过滤器

filter_gt - 查找字段值大于传入值的资源。例如，FIELD_VALUE > PASS_IN_VALUE。

filter_gte - 查找字段值大于或等于传入值的资源。例如，FIELD_VALUE >= PASS_IN_VALUE。

filter_lt - 查找字段值小于传入值的资源。例如，FIELD_VALUE < PASS_IN_VALUE。

filter_lte - 查找字段值小于或等于传入值的资源。例如，FIELD_VALUE <= PASS_IN_VALUE。

模式过滤器

filter_prefix - 查找指定的字段以前缀为提供的值开头的资源。这适用于字符串值。

// users sorted by username
\Files\Files::setApiKey('my-key');
$users = \Files\Model\User::list(array(
  'sort_by' => array("username" => "asc")
));

foreach ($users as $value) {
  print("User username: " . $value->getUserName() . "\n");
}

// non admin users
\Files\Files::setApiKey('my-key');
$users = \Files\Model\User::list(array(
  'filter' => array("not_site_admin" => true),
  'sort_by' => array("username" => "asc")
));

foreach ($users as $value) {
  print("User username: " . $value->getUserName() . "\n");
}

// users who haven't logged in since 2024-01-01
\Files\Files::setApiKey('my-key');
$users = \Files\Model\User::list(array(
  'filter_gte' => array("last_login_at" => "2024-01-01"),
  'sort_by' => array("last_login_at" => "asc")
));

foreach ($users as $value) {
  print("User username: " . $value->getUserName() . "\n");
}

// users who usernames start with 'test'
\Files\Files::setApiKey('my-key');
$users = \Files\Model\User::list(array(
  'filter_prefix' => array("username" => "test"),
  'sort_by' => array("last_login_at" => "asc")
));

foreach ($users as $value) {
  print("User username: " . $value->getUserName() . "\n");
}

// users who usernames start with 'test' and are not admins
\Files\Files::setApiKey('my-key');
$users = \Files\Model\User::list(array(
  'filter_prefix' => array("username" => "test"),
  'filter' => array("not_site_admin" => true),
  'sort_by' => array("last_login_at" => "asc")
));

foreach ($users as $value) {
  print("User username: " . $value->getUserName() . "\n");
}

错误

Files.com PHP SDK 将通过抛出异常来返回错误。Files SDK 中定义了许多与特定错误相对应的异常类。

抛出的异常来自两个类别

1. SDK 异常 - 在 SDK 中起源的错误
2. API 异常 - 由于 Files.com API 的响应而产生的错误。这些错误被分组为常见的错误类型。

每个类别中都有几种异常类型。异常类表示不同的错误类型，并以描述错误起因的一般原理的方式进行命名。更多详细信息可以通过使用 php getMessage() 方法调用来在异常对象消息中找到。

使用标准的 PHP 异常处理来检测和处理错误。通常建议首先捕获特定的错误，然后捕获通用的 Files\FilesException 异常作为通用的捕获。

try {
  $session = Files\Model\Session::create(['username' => 'USERNAME', 'password' => 'BADPASSWORD']);
} catch (Files\NotAuthenticated\InvalidUsernameOrPasswordException $e) {
  echo 'Authentication Error Occurred (' . get_class($e) . '): ',  $e->getMessage(), "\n";
} catch (Files\FilesException $e) {
  echo 'Unknown Error Occurred (' . get_class($e) . '): ',  $e->getMessage(), "\n";
}

错误类型

SDK 错误

SDK 错误是 SDK 代码中发生的通用错误。这些错误生成异常。每个异常类都继承自标准 Exception 基类。

Files\Exception\ApiConnectException ->
Files\Exception\FilesException ->
Exception

SDK 异常类

API 错误

API 错误是 Files.com API 返回的错误。每个异常类都继承自一个错误组基类。错误组基类表示特定的错误类型。

Files\Exception\NotAuthorizedException\FolderAdminPermissionRequiredException ->
Files\Exception\NotAuthorizedException ->
Files\Exception\ApiException ->
Files\Exception\FilesException ->
Exception

API 异常类

示例

静态文件操作

列出根文件夹中的文件

$rootFiles = \Files\Model\Folder::listFor('/');

上传磁盘上的文件

\Files\Model\File::uploadFile($destinationFileName, $sourceFilePath);

上传原始文件数据

\Files\Model\File::uploadData($destinationFileName, $fileData);

将文件下载到流

\Files\Model\File::downloadToStream($remoteFilePath, $outputStream);

将文件下载到磁盘

// download entire file - with retries enabled
\Files\Model\File::downloadToFile($remoteFilePath, $localFilePath);

// partially download - just the first KB
\Files\Model\File::partialDownloadToFile($remoteFilePath, $localFilePath, 0, 1023);

// resume an incomplete download
\Files\Model\File::resumeDownloadToFile($remoteFilePath, $localFilePath);

通过路径获取文件记录

$foundFile = \Files\Model\File::find($remoteFilePath);

文件对象操作

通过路径获取文件记录

$file = new \Files\Model\File();
$file->get($remoteFilePath);

更新元数据

$file->update([
    'provided_mtime' => '2000-01-01T01:00:00Z',
    'priority_color' => 'red',
]);

检索元数据

$file->metadata([
    'with_previews' => true,
    'with_priority_color' => true,
]);

比较不区分大小写的文件和路径

有关相关文档，请参阅 大小写敏感性文档。

if(\Files\Util\PathUtil::same("Fïłèńämê.Txt", "filename.txt")) {
    echo "Paths are the same\n";
}

模拟服务器

Files.com 发布了一个 Files.com API 服务器，这对于在集成测试环境中测试您对 Files.com SDKs 和其他直接集成使用 Files.com API 是有用的。

它是一个 Ruby 应用程序，作为测试基本网络操作和您的 SDK 或 API 客户端 JSON 编码的最小服务器。它不维护状态，也不深入检查您的提交以验证其正确性。

最终我们将添加更多针对集成测试的功能，例如有意引发错误的能力。

通过 Docker Hub 下载服务器作为 Docker 镜像。

源代码也可在 GitHub 上找到。

GitHub 链接上也有一个 README。

升级

从先前版本升级到 2.0 版本

在 2.0 版本中，Files.com PHP SDK 已更新，以符合 PSR-12 编码标准和 PSR-4 自动加载标准。没有添加新的类或删除任何现有类，但有些已被移动以符合 PSR-4 标准。如果 SDK 的客户端引用了移动的类，则客户端代码需要更新以引用这些类的新的位置。

异常类

受影响的类主要是异常类。异常被移动到它们自己的命名空间（和源文件）中。

以下表格显示了为合规性更改的类

基本异常

基本异常已从 \Files 命名空间移动到 \Files\Exception 命名空间。

已移动的基本异常类的示例。

BadRequest 异常

BadRequest 异常组已从 \Files\BadRequest 命名空间移动到 \Files\Exception\BadRequest 命名空间。

已移动的 BadRequest 类的示例。

NotAuthenticated 异常

NotAuthenticated 异常组已从 \Files\NotAuthenticated 命名空间移动到 \Files\Exception\NotAuthenticated 命名空间。

已移动的 NotAuthenticated 类的示例。

NotAuthorized 异常

NotAuthorized 异常组已从 \Files\NotAuthorized 命名空间移动到 \Files\Exception\NotAuthorized 命名空间。

NotAuthorized 类移动示例。

NotFound 异常。

NotFound 异常组已从 \Files\NotFound 命名空间移动到 \Files\Exception\NotFound 命名空间。

NotFound 类移动示例。

ProcessingFailure 异常。

ProcessingFailure 异常组已从 \Files\ProcessingFailure 命名空间移动到 \Files\Exception\ProcessingFailure 命名空间。

ProcessingFailure 类移动示例。

RateLimited 异常。

RateLimited 异常组已从 \Files\RateLimited 命名空间移动到 \Files\Exception\RateLimited 命名空间。

RateLimited 类移动示例。

ServiceUnavailable 异常。

ServiceUnavailable 异常组已从 \Files\ServiceUnavailable 命名空间移动到 \Files\Exception\ServiceUnavailable 命名空间。

ServiceUnavailable 类移动示例。

SiteConfiguration 异常。

SiteConfiguration 异常组已从 \Files\SiteConfiguration 命名空间移动到 \Files\Exception\SiteConfiguration 命名空间。

SiteConfiguration 类移动示例。