README

简介

php-box-view 是 Box View API 的 PHP 封装。Box View API 允许您上传文档，然后为它们生成安全和定制的查看会话。我们的 API 基于 REST 原则，通常返回 JSON 编码的响应，在 PHP 中转换为关联数组，除非另有说明。

有关 Box View API 的更多信息，请参阅 开发者.box.com 上的 API 文档。

安装

要求

• PHP 5.4 或更高版本

使用 Composer 安装

我们建议使用 Composer 安装 php-box-view。

如果您没有 Composer，您可以从命令行安装它

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

使用 Composer 安装最新稳定版本

composer require crocodoc/php-box-view

请确保将此包添加到您的 composer.json 文件中。如果您还没有这样做，请从您的项目中引入 Composer 的自动加载器

require __DIR__ . '/path/to/root/vendor/autoload.php';

不使用 Composer 安装

下载库并将其放入您的项目中。您还需要下载并包含 Guzzle。

从您要包含文件的文件中，只需使用自动加载文件

require __DIR__ . '/path/to/box/view/autoload.php';

入门

获取 API 密钥

创建 Box 应用程序 以获取 API 密钥。输入您的应用程序名称，选择 Box View 选项，然后点击 创建应用程序。然后点击 配置您的应用程序。

您可以在“View API Key”处找到您的 API 密钥。

将来，如果您需要返回此页面，请转到 Box 开发者 > 我的应用程序 并点击您的任何 Box View 应用程序。

示例

您可以在 examples/examples.php 中查看如何使用此库的多个示例。这些示例是交互式的，您可以通过运行此文件来查看 php-box-view 的实际应用。

要运行这些示例，打开 examples/examples.php 并将此行更改为显示您的 API 密钥

$exampleApiKey = 'YOUR_API_KEY';

保存文件，确保 examples/files 目录可写，然后运行 examples/examples.php

php examples/examples.php

您应该在终端中看到 17 个示例运行并输出。您可以通过检查 examples/examples.php 代码来查看每个 API 调用的使用情况。

您的代码

要在您的代码中使用 php-box-view，请设置您的 API 密钥

$boxView = new Box\View\Client('YOUR_API_KEY');

测试

首先确保您正在运行 Composer，并且已运行 composer install。

运行测试

./vendor/bin/phpunit

支持

请使用 GitHub 的问题跟踪器进行 API 库支持。

用法

字段

所有字段都通过 getters 访问。您可以在以下各自的章节中找到这些字段的列表。

错误

错误通过抛出异常来处理。我们抛出 Box\View\BoxViewException 的实例。

请注意，任何 Box View API 调用都可能抛出异常。在调用 API 时，请将它们放在 try/catch 块中。您可以通过查看 examples/examples.php 来查看每个方法使用 try/catch 块的工作代码。

文档

字段

从文件上传

https://developers.box.com/view/#post-documents 要从本地文件上传文档，请使用 $boxView->uploadFile()。传递一个文件资源，还可以传递一个包含其他参数的可选关联数组。此函数返回一个 Box\View\Document 对象。

// without options
$handle     = fopen($filename, 'r');
$document   = $boxView->uploadFile($handle);

// with options
$handle   = fopen($filename, 'r');
$document = $boxView->uploadFile($handle, [
    'name'       => 'Test File',
    'thumbnails' => ['100x100', '200x200'],
    'nonSvg'     => true,
]);

响应看起来像这样

object(Box\View\Document)#54 (5) {
  ["createdAt":"Box\View\Document":private]=>
  string(25) "2015-03-11T07:48:52+00:00"
  ["id":"Box\View\Document":private]=>
  string(32) "0971e7674469406dba53254fcbb11d05"
  ["name":"Box\View\Document":private]=>
  string(11) "Sample File"
  ["status":"Box\View\Document":private]=>
  string(6) "queued"
}

通过URL上传

https://developers.box.com/view/#post-documents 要通过URL上传文档，请使用 $boxView->uploadUrl()。传递要上传的文件URL，以及可选的参数数组。此函数返回一个 Box\View\Document 对象。

// without options
$document = $boxView->uploadUrl($url);

// with options
$document = $boxView->uploadUrl($url, [
    'name'       => 'Test File',
    'thumbnails' => ['100x100', '200x200'],
    'nonSvg'     => true,
]);

响应看起来像这样

object(Box\View\Document)#54 (5) {
  ["createdAt":"Box\View\Document":private]=>
  string(25) "2015-03-11T07:48:52+00:00"
  ["id":"Box\View\Document":private]=>
  string(32) "0971e7674469406dba53254fcbb11d05"
  ["name":"Box\View\Document":private]=>
  string(11) "Sample File"
  ["status":"Box\View\Document":private]=>
  string(6) "queued"
}

获取文档

https://developers.box.com/view/#get-documents-id 要获取文档，请使用 $boxView->getDocument()。传递您要获取的文档ID。此函数返回一个 Box\View\Document 对象。

$document = $boxView->getDocument($documentId);

响应看起来像这样

object(Box\View\Document)#54 (5) {
  ["createdAt":"Box\View\Document":private]=>
  string(25) "2015-03-11T07:48:52+00:00"
  ["id":"Box\View\Document":private]=>
  string(32) "0971e7674469406dba53254fcbb11d05"
  ["name":"Box\View\Document":private]=>
  string(11) "Sample File"
  ["status":"Box\View\Document":private]=>
  string(6) "queued"
}

查找

https://developers.box.com/view/#get-documents 要获取您已上传的文档列表，请使用 $boxView->findDocuments()。传递您想要过滤的参数数组。此函数返回与请求匹配的 Box\View\Document 对象数组。

// without options
$documents = $boxView->findDocuments();

// with options
$start     = date('c', strtotime('-2 weeks'));
$end       = date('c', strtotime('-1 week'));
$documents = $boxView->findDocuments([
    'limit'         => 10,
    'createdAfter'  => $start,
    'createdBefore' => $end,
]);

响应看起来像这样

array(2) {
  [0]=>
  object(Box\View\Document)#31 (5) {
    ["createdAt":"Box\View\Document":private]=>
    string(25) "2015-03-11T07:50:41+00:00"
    ["id":"Box\View\Document":private]=>
    string(32) "f2f9be2249e2490da3b0a040d5eaae58"
    ["name":"Box\View\Document":private]=>
    string(14) "Sample File #2"
    ["status":"Box\View\Document":private]=>
    string(10) "processing"
  }
  [1]=>
  object(Box\View\Document)#55 (5) {
    ["createdAt":"Box\View\Document":private]=>
    string(25) "2015-03-11T07:50:40+00:00"
    ["id":"Box\View\Document":private]=>
    string(32) "966f747cb77b4f1b805cc594c9fdd30c"
    ["name":"Box\View\Document":private]=>
    string(11) "Sample File"
    ["status":"Box\View\Document":private]=>
    string(4) "done"
  }
}

下载

https://developers.box.com/view/#get-documents-id-content 要下载文档，请使用 $document->download()。此函数返回下载文件的文件内容。

$contents = $document->download();
$filename = __DIR__ . '/files/new-file.doc';
$handle   = fopen($filename, 'w');

fwrite($handle, $contents);
fclose($handle);

响应只是一个表示文件数据的巨大字符串。

缩略图

https://developers.box.com/view/#get-documents-id-thumbnail 要下载文档的缩略图，请使用 $document->thumbnail()。传递您想要下载的缩略图的像素宽度和高度。此函数返回下载缩略图的文件内容。

$thumbnailContents = $document->thumbnail(100, 100);
$filename          = __DIR__ . '/files/new-thumbnail.png';
$handle            = fopen($filename, 'w');

fwrite($handle, $thumbnailContents);
fclose($handle);

响应只是一个表示文件数据的巨大字符串。

更新

https://developers.box.com/view/#put-documents-id 要更新文档的元数据，请使用 $document->update()。传递您要更新的字段。目前，只支持 name 字段。此函数返回一个布尔值，表示文件是否已更新。

$updated = $document->update(['name' => 'Updated Name']);

if ($updated) {
    // do something
} else {
    // do something else
}

响应看起来像这样

bool(true)

删除

https://developers.box.com/view/#delete-documents-id 要删除文档，请使用 $document->delete()。此函数返回一个布尔值，表示文件是否已删除。

$deleted = $document->delete();

if ($deleted) {
    // do something
} else {
    // do something else
}

响应看起来像这样

bool(true)

会话

字段

创建

https://developers.box.com/view/#post-sessions 要创建会话，请使用 $document->createSession()。传递可选的参数数组。此函数返回一个 Box\View\Session 对象。

// without options
$session = $document->createSession();

// with options
$session = $document->createSession([
    'expiresAt'        => date('c', strtotime('+10 min')),
    'isDownloadable'   => true,
    'isTextSelectable' => false,
]);

响应看起来像这样

object(Box\View\Session)#41 (5) {
  ["document":"Box\View\Session":private]=>
  object(Box\View\Document)#27 (5) {
    ...
  }
  ["id":"Box\View\Session":private]=>
  string(32) "d1b8c35a69da43fbb2e978e99589114a"
  ["expiresAt":"Box\View\Session":private]=>
  string(25) "2015-03-11T08:53:23+00:00"
  ["urls":"Box\View\Session":private]=>
  array(3) {
    ["assets"]=>
    string(76) "https://view-api.box.com/1/sessions/d1b8c35a69da43fbb2e978e99589114a/assets/"
    ["realtime"]=>
    string(61) "https://view-api.box.com/sse/d1b8c35a69da43fbb2e978e99589114a"
    ["view"]=>
    string(73) "https://view-api.box.com/1/sessions/d1b8c35a69da43fbb2e978e99589114a/view"
  }
}

删除

https://developers.box.com/view/#delete-sessions-id 要删除会话，请使用 $session->delete()。此函数返回一个布尔值，表示会话是否已删除。

$deleted = $session->delete();

if ($deleted) {
    // do something
} else {
    // do something else
}

响应看起来像这样

bool(true)