chancegarcia/php-box-sdk

PHP SDK and API client for the Box API v2024.0, supporting OAuth2 and JWT/S2S authentication, file and folder operations, uploads, webhook signature verification, typed models, and PSR-3 logging.

v1.0.3 2026-05-19 04:27 UTC

Requires

• php: >=8.4
• ext-fileinfo: *
• ext-openssl: *
• ext-pdo: *
• doctrine/collections: ^2.2
• guzzlehttp/guzzle: ^7.0
• guzzlehttp/psr7: ^2.0
• monolog/monolog: ^3.0
• psr/event-dispatcher: ^1.0
• psr/http-message: ^2.0
• psr/log: ^3
• symfony/console: ^7.4|^8
• symfony/dotenv: ^7.4|^8

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.5
• roave/security-advisories: dev-latest
• slevomat/coding-standard: ^8.29
• squizlabs/php_codesniffer: ^4.0

Apache-2.0

• chance garcia

• oauth2
• Guzzle
• sdk
• psr-3
• webhook
• jwt
• API-Client
• box
• file-upload
• php-sdk
• box-sdk
• cloud-storage
• file-storage
• box-api
• box-api-v2024
• box-v2
• box-platform

README

A modern PHP SDK for interacting with the Box.com API.

Status: v1.0.0 released.

This library is designed as a boundary layer for Box API access, suitable for standalone use or integration into frameworks like Symfony.

Requirements

• PHP 8.4 or higher
• ext-fileinfo

Installation

composer require chancegarcia/php-box-sdk

Quickstart

OAuth2 Workflow

The recommended setup uses BoxClientFactory with an EnvConfigProvider, which reads credentials from environment variables (BOX_OAUTH_CLIENT_ID, BOX_OAUTH_CLIENT_SECRET, etc.):

use Box\Service\BoxClientFactory;
use Box\Service\EnvConfigProvider;

$factory = new BoxClientFactory(new EnvConfigProvider());
$client  = $factory->createClient();

Generate the authorization URL and redirect the user:

$authUrl = $client->buildAuthorizationUrl();
// Redirect user to $authUrl

After the user authorizes and is redirected back with a code, exchange it for a token:

$client->setAuthorizationCode($_GET['code']);
$token = $client->exchangeAuthorizationCodeForToken();

JWT / Server-to-Server

For server-to-server integrations (no browser redirect needed), set BOX_AUTH_MODE=jwt and the BOX_JWT_* environment variables, then:

use Box\Service\BoxClientFactory;
use Box\Service\EnvConfigProvider;

$configProvider = new EnvConfigProvider();
$factory        = new BoxClientFactory($configProvider);
$client         = $factory->createClientForCurrentMode(); // JWT client when BOX_AUTH_MODE=jwt

See the Programmatic Usage Guide for enterprise and app-user token exchange examples.

File and Folder Operations

use Box\Http\FileStream;

$client->setToken($token);

// Upload a local file
$result = $client->uploadFileToBox('/path/to/file.txt', '12345');

// Upload via stream (no local file needed)
$stream = FileStream::fromString('Hello World', 'hello.txt');
$result = $client->uploadFileToBox($stream, '0'); // '0' is the root folder ID

// Get a folder
$folder = $client->getFolder('12345');

Advanced Documentation

For in-depth architectural guidance, library integration patterns, and advanced usage:

• Programmatic Usage Guide — OAuth2, JWT/S2S, token storage, error handling, file streaming
• CLI Test Harness Guide — bin/box-sdk commands for manual verification
• v1.0 Migration Guide — upgrading from v0.11

Development and Quality Checks

composer review    # Run all checks (recommended before pushing)
composer test      # PHPUnit
composer analyse   # PHPStan
composer cs:check  # PHP_CodeSniffer
composer cs:fix    # Fix code style automatically
composer lint      # PHP syntax check

See also:

• Changelog
• Documentation Index

License

Apache 2.0 License. See LICENSE for details.

This project was previously distributed under the MIT License. As of v1.0.0 it is relicensed under Apache 2.0.