2amigos / php-box-view
PHP wrapper for the Box View API
Requires
- php: >=5.4
- guzzlehttp/guzzle: > 6.0 <7.0
Requires (Dev)
- mockery/mockery: ~0.9
- phpunit/phpunit: ~4.4
This package is auto-updated.
Last update: 2024-10-16 06:09:44 UTC
README
Introduction
php-box-view is a PHP wrapper for the Box View API. The Box View API lets you upload documents and then generate secure and customized viewing sessions for them. Our API is based on REST principles and generally returns JSON encoded responses, and in PHP are converted to associative arrays unless otherwise noted.
For more information about the Box View API, see the API docs at developers.box.com.
Installation
Requirements
- PHP 5.4 or newer
Install with Composer
We recommend installing php-box-view
using Composer.
If you don't have Composer, you can install it from the command line:
curl -sS https://getcomposer.org/installer | php
Use Composer to install the latest stable version:
composer require crocodoc/php-box-view
Make sure to add this package to your composer.json file. And if you aren't doing this already, require Composer's autoloader from your project:
require __DIR__ . '/path/to/root/vendor/autoload.php';
Install without Composer
Download the library and put it in your project. You will also need to download and include Guzzle.
From the file you want to include it from, just use the autoload file:
require __DIR__ . '/path/to/box/view/autoload.php';
Getting Started
Get an API Key
Create a Box Application to get an API key.
Enter your application name, click the option for Box View
, and click Create Application
.
Then click Configure your application
.
You can find your API key where it says View API Key
.
In the future, if you need to return to this page, go to Box Developers > My Applications and click on any of your Box View apps.
Examples
You can see a number of examples on how to use this library in examples/examples.php
.
These examples are interactive and you can run this file to see php-box-view
in action.
To run these examples, open up examples/examples.php
and change this line to show your API key:
$exampleApiKey = 'YOUR_API_KEY';
Save the file, make sure the examples/files
directory is writable, and then run examples/examples.php
:
php examples/examples.php
You should see 17 examples run with output in your terminal.
You can inspect the examples/examples.php
code to see each API call being used.
Your Code
To start using php-box-view
in your code, set your API key:
$boxView = new Box\View\Client('YOUR_API_KEY');
Tests
First make sure you're running Composer and that you've run composer install
.
Run the tests:
./vendor/bin/phpunit
Support
Please use GitHub's issue tracker for API library support.
Usage
Fields
All fields are accessed using getters. You can find a list of these fields below in their respective sections.
Errors
Errors are handled by throwing exceptions.
We throw instances of Box\View\BoxViewException
.
Note that any Box View API call can throw an exception.
When making API calls, put them in a try/catch block.
You can see examples/examples.php
to see working code for each method using try/catch blocks.
Document
Fields
Upload from File
https://developers.box.com/view/#post-documents
To upload a document from a local file, use $boxView->uploadFile()
.
Pass in a file resource, and also an optional associative array of other params.
This function returns a Box\View\Document
object.
// 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, ]);
The response looks like this:
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" }
Upload by URL
https://developers.box.com/view/#post-documents
To upload a document by a URL, use $boxView->uploadUrl()
.
Pass in the URL of the file you want to upload, and also an optional associative array of other params.
This function returns a Box\View\Document
object.
// without options $document = $boxView->uploadUrl($url); // with options $document = $boxView->uploadUrl($url, [ 'name' => 'Test File', 'thumbnails' => ['100x100', '200x200'], 'nonSvg' => true, ]);
The response looks like this:
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" }
Get Document
https://developers.box.com/view/#get-documents-id
To get a document, use $boxView->getDocument()
.
Pass in the ID of the document you want to get.
This function returns a Box\View\Document
object.
$document = $boxView->getDocument($documentId);
The response looks like this:
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" }
Find
https://developers.box.com/view/#get-documents
To get a list of documents you've uploaded, use $boxView->findDocuments()
.
Pass an optional associative array of parameters you want to filter by.
This function returns an array of Box\View\Document
objects matching the request.
// 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, ]);
The response looks like this:
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" } }
Download
https://developers.box.com/view/#get-documents-id-content
To download a document, use $document->download()
.
This function returns the contents of the downloaded file.
$contents = $document->download(); $filename = __DIR__ . '/files/new-file.doc'; $handle = fopen($filename, 'w'); fwrite($handle, $contents); fclose($handle);
The response is just a giant string representing the data of the file.
Thumbnail
https://developers.box.com/view/#get-documents-id-thumbnail
To download a document, use $document->thumbnail()
.
Pass in the width and height in pixels of the thumbnail you want to download.
This function returns the contents of the downloaded thumbnail.
$thumbnailContents = $document->thumbnail(100, 100); $filename = __DIR__ . '/files/new-thumbnail.png'; $handle = fopen($filename, 'w'); fwrite($handle, $thumbnailContents); fclose($handle);
The response is just a giant string representing the data of the file.
Update
https://developers.box.com/view/#put-documents-id
To update the metadata of a document, use $document->update()
.
Pass in the fields you want to update.
Right now, only the name
field is supported.
This function returns a boolean of whether the file was updated or not.
$updated = $document->update(['name' => 'Updated Name']); if ($updated) { // do something } else { // do something else }
The response looks like this:
bool(true)
Delete
https://developers.box.com/view/#delete-documents-id
To delete a document, use $document->delete()
.
This function returns a boolean of whether the file was deleted or not.
$deleted = $document->delete(); if ($deleted) { // do something } else { // do something else }
The response looks like this:
bool(true)
Session
Fields
Create
https://developers.box.com/view/#post-sessions
To create a session, use $document->createSession()
.
Pass in an optional associative array of params.
This function returns a Box\View\Session
object.
// without options $session = $document->createSession(); // with options $session = $document->createSession([ 'expiresAt' => date('c', strtotime('+10 min')), 'isDownloadable' => true, 'isTextSelectable' => false, ]);
The response looks like this:
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" } }
Delete
https://developers.box.com/view/#delete-sessions-id
To delete a session, use $session->delete()
.
This function returns a boolean of whether the session was deleted or not.
$deleted = $session->delete(); if ($deleted) { // do something } else { // do something else }
The response looks like this:
bool(true)