Box Sdk
, (*1)
, (*2)
Description
This is an unofficial Box Php Sdk., (*3)
Toc
Support
, (*4)
Installation
Install it through composer., (*5)
{
"require": {
"adammbalogh/box-sdk": "@stable"
}
}
tip: you should browse the adammbalogh/box-sdk
page to choose a stable version to use, avoid the @stable meta constraint., (*6)
Authorization
Your goal is to obtain a valid access token., (*7)
Authorize
<?php
use AdammBalogh\Box\Client\OAuthClient;
use AdammBalogh\KeyValueStore\KeyValueStore;
use AdammBalogh\KeyValueStore\Adapter\NullAdapter;
use AdammBalogh\Box\Exception\ExitException;
use AdammBalogh\Box\Exception\OAuthException;
use GuzzleHttp\Exception\ClientException;
$clientId = 'clientid';
$clientSecret = 'clientsecret';
$redirectUri = 'http://example.com/my-box-app.php';
$keyValueStore = new KeyValueStore(new NullAdapter());
$oAuthClient = new OAuthClient($keyValueStore, $clientId, $clientSecret, $redirectUri);
try {
$oAuthClient->authorize();
} catch (ExitException $e) {
# Location header has set (box's authorize page)
# Instead of an exit call it throws an ExitException
exit;
} catch (OAuthException $e) {
# e.g. Invalid user credentials
# e.g. The user denied access to your application
} catch (ClientException $e) {
# e.g. if $_GET['code'] is older than 30 sec
}
$accessToken = $oAuthClient->getAccessToken();
The $keyValueStore object is responsible for obtain/save the access token. The example above uses a NullAdapter for a KeyValueStore, this means it does not obtain or save anything, so authorizes on each call., (*8)
If you want to save the access (and the refresh) token persistently, you should check the other adapters of the KeyValueStore package, here., (*9)
Revoke tokens
$oAuthClient->revokeTokens();
Get access token Ttl
/* @var int $ttl Access token's time to live */
$ttl = $oAuthClient->getAccessTokenTtl();
Request
Extended Request
Here you can see an example request to the View Api. It calls the UrlDocumentUpload command., (*10)
Many of the commands are able to include an Extended Request object. With an Extended Request object you can
inject your extra Headers, Url Parameters or Request Body Attributes., (*11)
<?php
use AdammBalogh\Box\ViewClient;
use AdammBalogh\Box\Client\View\ApiClient;
use AdammBalogh\Box\Client\View\UploadClient;
use AdammBalogh\Box\Command\View;
use AdammBalogh\Box\Request\ExtendedRequest;
$apiKey = 'apikey';
$viewClient = new ViewClient(new ApiClient($apiKey), new UploadClient($apiKey));
$er = new ExtendedRequest();
$er->setHeader('Content-Type', 'application/json');
$er->addQueryField('fields', 'status');
$er->setPostBodyField('name', 'file-name');
$command = new View\Document\UrlDocumentUpload('https://cloud.box.com/shared/static/zzxlzc38hq7u1u5jdteu.pdf', $er);
Response
Handle Response
You can get 5 important response values:
* $response->getStatusCode(); # e.g. '201'
* $response->getReasonPhrase(); # e.g. 'Created'
* $response->getHeaders(); # array of response headers ['header name' => 'header value']
* $response->json(); # parse json response as an array
* (string)$response->getBody();, (*12)
<?php
use AdammBalogh\Box\ViewClient;
use AdammBalogh\Box\Client\View\ApiClient;
use AdammBalogh\Box\Client\View\UploadClient;
use AdammBalogh\Box\Command\View;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$apiKey = 'apikey';
$viewClient = new ViewClient(new ApiClient($apiKey), new UploadClient($apiKey));
$command = new View\Document\ListDocument();
$response = ResponseFactory::getResponse($viewClient, $command);
if ($response instanceof SuccessResponse) {
$response->getStatusCode();
$response->getReasonPhrase();
$response->getHeaders();
$response->json();
(string)$response->getBody();
} elseif ($response instanceof ErrorResponse) {
# same as above
}
Content Api
Create Client
<?php
use AdammBalogh\Box\ContentClient;
use AdammBalogh\Box\Client\Content\ApiClient;
use AdammBalogh\Box\Client\Content\UploadClient;
$accessToken = 'accesstoken';
$contentClient = new ContentClient(new ApiClient($accessToken), new UploadClient($accessToken));
Commands
User Commands
Get Current User Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\User\GetCurrentUser();
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Folder Commands
Copy Folder Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\Folder\CopyFolder('sourceFolderId', 'destinationFolderId');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Create Folder Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\Folder\CreateFolder('folderName', 'parentFolderId');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Create Shared Folder Link Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
use AdammBalogh\Box\Request\ExtendedRequest;
$er = new ExtendedRequest();
$er->setPostBodyField('shared_link', ['access'=>'open']);
$command = new Content\Folder\CreateSharedFolderLink('folderId', $er);
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Delete Folder Command
✔ Extended Request, (*13)
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\Folder\DeleteFolder('folderId');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Get Folder Info Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\Folder\GetFolderInfo('folderId');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
List Folder Command
✔ Extended Request, (*14)
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\Folder\ListFolder('folderId');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
List Folder Collaborations Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\Folder\ListFolderCollaborations('folderId');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Update Folder Info Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
use AdammBalogh\Box\Request\ExtendedRequest;
$er = new ExtendedRequest();
$er->setPostBodyField('name', 'file-name');
$command = new Content\Folder\UpdateFolderInfo('folderId', $er);
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
File Commands
Copy File Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\File\CopyFile('fileId', 'folderId');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Create Shared File Link Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
use AdammBalogh\Box\Request\ExtendedRequest;
$er = new ExtendedRequest();
$er->setPostBodyField('shared_link', ['access'=>'open']);
$command = new Content\File\CreateSharedFileLink('fileId', $er);
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Delete File Command
✔ Extended Request, (*15)
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\File\DeleteFile('fileId');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Download File Command
✔ Extended Request, (*16)
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\File\DownloadFile('fileId');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Get File Info Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\File\GetFileInfo('fileId');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Pre Flight Existing File Check Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\File\PreFlightExistingFileCheck('fileId', fileSize);
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Pre Flight New File Check Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\File\PreFlightNewFileCheck('fileName', fileSize, 'parentFolderId');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Update File Info Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
use AdammBalogh\Box\Request\ExtendedRequest;
$er = new ExtendedRequest();
$er->setPostBodyField('name', 'file-name');
$er->setPostBodyField('description', 'file-description');
$command = new Content\File\UpdateFileInfo('fileId', $er);
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Upload File Command
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\File\UploadFile('fileName', 'parentFolderId', 'content');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Upload New File Version Command
✔ Extended Request, (*17)
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\File\UploadNewFileVersion('fileId', 'content');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Search Commands
Search Content Command
✔ Extended Request, (*18)
<?php
use AdammBalogh\Box\Command\Content;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new Content\Search\SearchContent('query');
$response = ResponseFactory::getResponse($contentClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
View Api
Create Client
<?php
use AdammBalogh\Box\ViewClient;
use AdammBalogh\Box\Client\View\ApiClient;
use AdammBalogh\Box\Client\View\UploadClient;
$apiKey = 'apikey';
$viewClient = new ViewClient(new ApiClient($apiKey), new UploadClient($apiKey));
Commands
Document Commands
Delete Document Command
<?php
use AdammBalogh\Box\Command\View;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new View\Document\DeleteDocument('documentId');
$response = ResponseFactory::getResponse($viewClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Get Document Content Command ☢
<?php
use AdammBalogh\Box\Command\View;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new View\Document\GetDocumentContent('documentId', 'zip'); # extension can be '', 'zip' or 'pdf'
$response = $viewClient->request($command);
echo (string)$response->getBody(); # the content of the document
Get Document Info Command
✔ Extended Request, (*19)
<?php
use AdammBalogh\Box\Command\View;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new View\Document\GetDocumentInfo('documentId');
$response = ResponseFactory::getResponse($viewClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Get Document Thumbnail Command
✔ Extended Request, (*20)
<?php
use AdammBalogh\Box\Command\View;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new View\Document\GetDocumentThumbnail('documentId');
$response = ResponseFactory::getResponse($viewClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
List Document Command
✔ Extended Request, (*21)
<?php
use AdammBalogh\Box\Command\View;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new View\Document\ListDocument();
$response = ResponseFactory::getResponse($viewClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Multipart Document Upload Command
✔ Extended Request, (*22)
<?php
use AdammBalogh\Box\Command\View;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new View\Document\MultipartDocumentUpload('content', 'filename.pdf');
$response = ResponseFactory::getResponse($viewClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Update Document Info Command
<?php
use AdammBalogh\Box\Command\View;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new View\Document\UpdateDocumentInfo('documentId', 'newFileName');
$response = ResponseFactory::getResponse($viewClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Url Document Upload Command
✔ Extended Request, (*23)
<?php
use AdammBalogh\Box\Command\View;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new View\Document\UrlDocumentUpload('urlOfTheDocument');
$response = ResponseFactory::getResponse($viewClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Session Commands
Create Document Session Command
✔ Extended Request, (*24)
<?php
use AdammBalogh\Box\Command\View;
use AdammBalogh\Box\Factory\ResponseFactory;
use AdammBalogh\Box\GuzzleHttp\Message\SuccessResponse;
use AdammBalogh\Box\GuzzleHttp\Message\ErrorResponse;
$command = new View\Session\CreateDocumentSession('documentId');
$response = ResponseFactory::getResponse($viewClient, $command);
if ($response instanceof SuccessResponse) {
# ...
} elseif ($response instanceof ErrorResponse) {
# ...
}
Wrappers
Search Path Wrapper
It wraps the Search Content Command to able to get an Entry object from a path string (like /root/dir_1/dir_2, or /pictures/img.png), (*25)
<?php
use AdammBalogh\Box\Wrapper\SearchPath;
use AdammBalogh\Box\Wrapper\Response\FolderEntry;
use AdammBalogh\Box\Wrapper\Response\FileEntry;
$wrapper = new SearchPath($contentClient);
$entry = $wrapper->getEntry('/my-dir/example_dir');
if ($entry instanceof FolderEntry) {
$entry->identity; # folderId
# here you can create your own command, because now you have the folder id!
} elseif ($entry instanceof FileEntry) {
$entry->identity;
}
Create Folders Wrapper
It wraps the Create Folder Command to able to create folders implicitly., (*26)
<?php
use AdammBalogh\Box\Wrapper\CreateFolders;
$wrapper = new CreateFolders($contentClient);
$lastFolderId = $wrapper->create('/dir_1/dir_2/dir_3/dir_4');
# $lastFolderId means dir_4's id
Wallogit.com
