PHPackages                             tigusigalpa/dropbox-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. tigusigalpa/dropbox-php

ActiveLibrary[API Development](/categories/api)

tigusigalpa/dropbox-php
=======================

Modern PHP SDK for Dropbox API v2 integration with Laravel support

v1.1.1(2mo ago)131MITPHPPHP ^8.1CI failing

Since Dec 20Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/tigusigalpa/dropbox-php)[ Packagist](https://packagist.org/packages/tigusigalpa/dropbox-php)[ Docs](https://github.com/tigusigalpa/dropbox-php)[ GitHub Sponsors](https://github.com/tigusigalpa)[ RSS](/packages/tigusigalpa-dropbox-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (4)Versions (3)Used By (0)

Dropbox PHP SDK
===============

[](#dropbox-php-sdk)

[![Dropbox PHP SDK](https://private-user-images.githubusercontent.com/2721390/528842795-361952c5-03d0-4ef6-b0b8-3106bb4ca3be.jpg?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzUxMjYxNjMsIm5iZiI6MTc3NTEyNTg2MywicGF0aCI6Ii8yNzIxMzkwLzUyODg0Mjc5NS0zNjE5NTJjNS0wM2QwLTRlZjYtYjBiOC0zMTA2YmI0Y2EzYmUuanBnP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDQwMiUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjA0MDJUMTAzMTAzWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9YmU5ZjIxYTRlMGRjNjVmZDUzMjUzZDZjN2EwZmJhYzFiN2Q0MDMzMjUyZTZkZjc0NjI5NTI3NDcxYTExNWVlYiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.uW7VCkU5GpEgO_Usf3xvhOzcgSRwT-q2ScVJPEDfIag)](https://private-user-images.githubusercontent.com/2721390/528842795-361952c5-03d0-4ef6-b0b8-3106bb4ca3be.jpg?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzUxMjYxNjMsIm5iZiI6MTc3NTEyNTg2MywicGF0aCI6Ii8yNzIxMzkwLzUyODg0Mjc5NS0zNjE5NTJjNS0wM2QwLTRlZjYtYjBiOC0zMTA2YmI0Y2EzYmUuanBnP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDQwMiUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjA0MDJUMTAzMTAzWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9YmU5ZjIxYTRlMGRjNjVmZDUzMjUzZDZjN2EwZmJhYzFiN2Q0MDMzMjUyZTZkZjc0NjI5NTI3NDcxYTExNWVlYiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.uW7VCkU5GpEgO_Usf3xvhOzcgSRwT-q2ScVJPEDfIag)

[![Latest Version](https://camo.githubusercontent.com/3a9a564957d963d19ca4a7734a6d0e29a97872051fd67def6122b88b8989c5d5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f74696775736967616c70612f64726f70626f782d7068702e737667)](https://packagist.org/packages/tigusigalpa/dropbox-php)[![License](https://camo.githubusercontent.com/0ef25bbb2f4279971d71afb01c33b42ed79384a3e7ba5a46b836a3dd15d7dc96/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f74696775736967616c70612f64726f70626f782d7068702e737667)](https://github.com/tigusigalpa/dropbox-php/blob/main/LICENSE)[![PHP Version](https://camo.githubusercontent.com/124163848c80c723bbb6787079bd551f5fe07b5e1f69f74a1845862371e82e6c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f74696775736967616c70612f64726f70626f782d7068702e737667)](https://packagist.org/packages/tigusigalpa/dropbox-php)

PHP SDK for [Dropbox API v2](https://www.dropbox.com/developers/documentation/http/documentation) with Laravel 8-12 support. Provides a type-safe interface for working with Dropbox storage, file sharing, and collaboration from PHP 8.1+ applications. Can be used standalone or as a Laravel package with auto-registered service provider and facade.

> 📖 **[Full documentation available on Wiki](https://github.com/tigusigalpa/dropbox-php/wiki)**

What's Inside
-------------

[](#whats-inside)

The package covers all major Dropbox API v2 endpoints: files, sharing, users, file requests, and Paper. It handles OAuth 2.0 flows, chunked uploads for large files, and batch operations. Error handling is built around a dedicated exception class with access to Dropbox error details.

Laravel users get a service provider, facade, and config publishing out of the box. Everyone else can use `DropboxClient` directly — no framework required.

**🌐 Language:** English | [Русский](README-ru.md)

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Supported Endpoints](#supported-endpoints)
- [What's Inside](#whats-inside)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Detailed Usage Examples](#detailed-usage-examples)
    - [Working with Files](#working-with-files)
    - [Sharing](#sharing)
    - [Image Hosting with Direct Links](#image-hosting-with-direct-links)
    - [Users and Account](#users-and-account)
    - [File Requests](#file-requests)
    - [Paper Documents](#paper-documents)
    - [Batch Operations](#batch-operations)
- [OAuth 2.0 Authorization](#oauth-20-authorization)
- [Laravel Usage](#laravel-usage)
- [Error Handling](#error-handling)
- [Advanced Examples](#advanced-examples)
- [Package Structure](#package-structure)
- [Testing](#testing)
- [Contributing](#contributing)
- [Changelog](#changelog)
- [License](#license)

Features
--------

[](#features)

- ✅ **Dropbox API v2** — all major endpoints covered
- 🚀 **Laravel 8–12** — service provider, facade, config publishing
- 🎯 **PHP 8.1+** — typed properties, enums, named arguments
- 📦 **Standalone** — works without any framework
- 🔐 **OAuth 2.0** — authorization URL, token exchange, refresh
- 📝 **Documentation** — usage examples and API reference
- 🧪 **Tests** — PHPUnit test suite included
- 🎨 **Clean API** — `$client->files->upload(...)` style
- ⚡ **Chunked Upload** — large files uploaded in configurable chunks
- 🔄 **Batch Operations** — copy, move, delete up to 1000 files per call

Supported Endpoints
-------------------

[](#supported-endpoints)

- **Files** - Upload, download, move, copy, delete, search, and manage files/folders
- **Sharing** - Create shared links, manage folder/file sharing, collaborate with team members
- **Users** - Get account information, space usage, and user features
- **File Requests** - Create and manage file request forms
- **Paper** - Create, edit, and manage Dropbox Paper documents
- **Check** - API connectivity and health checks

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Guzzle HTTP client 7.0+
- Laravel 8.0+ (optional, for Laravel integration)

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require tigusigalpa/dropbox-php
```

### Laravel Installation

[](#laravel-installation)

The package will automatically register its service provider and facade.

Publish the configuration file:

```
php artisan vendor:publish --tag=dropbox-config
```

Add your Dropbox credentials to your `.env` file:

```
DROPBOX_ACCESS_TOKEN=your_access_token_here
DROPBOX_APP_KEY=your_app_key
DROPBOX_APP_SECRET=your_app_secret
DROPBOX_REDIRECT_URI=https://your-app.com/callback
```

Quick Start
-----------

[](#quick-start)

### Obtaining Access Token

[](#obtaining-access-token)

1. Create a Dropbox app at [Dropbox App Console](https://www.dropbox.com/developers/apps)
2. Choose your app type and permissions
3. Generate an access token from the app settings page

For production applications, implement the OAuth 2.0 flow (see [OAuth 2.0 Authorization](#oauth-20-authorization)section).

### Basic Usage (Standalone PHP)

[](#basic-usage-standalone-php)

```
use Tigusigalpa\Dropbox\DropboxClient;

$client = new DropboxClient('your_access_token');

// Get current user account info
$account = $client->users->getCurrentAccount();
echo "Hello, " . $account['name']['display_name'];

// Upload a file
$result = $client->files->upload(
    '/Documents/hello.txt',
    'Hello, Dropbox!',
    'add'
);

// List folder contents
$contents = $client->files->listFolder('/Documents');
foreach ($contents['entries'] as $entry) {
    echo $entry['name'] . "\n";
}

// Download a file
$file = $client->files->download('/Documents/hello.txt');
file_put_contents('local-hello.txt', $file['content']);

// Create a shared link
$link = $client->sharing->createSharedLinkWithSettings('/Documents/hello.txt');
echo "Share this link: " . $link['url'];
```

### Laravel Usage

[](#laravel-usage)

```
use Tigusigalpa\Dropbox\Facades\Dropbox;

// Using Facade
$account = Dropbox::users()->getCurrentAccount();

// Using Dependency Injection
use Tigusigalpa\Dropbox\DropboxClient;

class FileController extends Controller
{
    public function upload(Request $request, DropboxClient $dropbox)
    {
        $content = file_get_contents($request->file('document')->path());

        $result = $dropbox->files->upload(
            '/uploads/' . $request->file('document')->getClientOriginalName(),
            $content
        );

        return response()->json($result);
    }
}
```

Detailed Usage Examples
-----------------------

[](#detailed-usage-examples)

### Working with Files

[](#working-with-files)

#### Uploading Files

[](#uploading-files)

```
// Simple upload
$client->files->upload('/path/to/file.txt', 'File content');

// Upload with options
$client->files->upload(
    '/path/to/file.txt',
    $content,
    'overwrite',  // mode: 'add', 'overwrite', or 'update'
    true,         // autorename if conflict
    false,        // mute notifications
    false         // strict conflict checking
);

// Upload from local file
$content = file_get_contents('/local/path/file.pdf');
$client->files->upload('/Dropbox/file.pdf', $content);

// Upload with metadata
$result = $client->files->upload(
    '/Documents/report.pdf',
    file_get_contents('local-report.pdf'),
    'add',
    false,
    false,
    false
);
echo "Uploaded file: {$result['name']}, size: {$result['size']} bytes";
```

#### Large File Upload (Chunked)

[](#large-file-upload-chunked)

```
// Start upload session
$session = $client->files->uploadSessionStart($firstChunk, false);
$sessionId = $session['session_id'];

// Append chunks
$offset = strlen($firstChunk);
$client->files->uploadSessionAppend($sessionId, $offset, $secondChunk, false);

// Finish upload
$offset += strlen($secondChunk);
$result = $client->files->uploadSessionFinish(
    $sessionId,
    $offset,
    $lastChunk,
    ['path' => '/large-file.zip', 'mode' => 'add']
);

// Complete example for uploading a large file
$filePath = '/path/to/large-video.mp4';
$chunkSize = 4 * 1024 * 1024; // 4MB chunks
$file = fopen($filePath, 'rb');

// First chunk
$firstChunk = fread($file, $chunkSize);
$session = $client->files->uploadSessionStart($firstChunk, false);
$offset = strlen($firstChunk);

// Remaining chunks
while (!feof($file)) {
    $chunk = fread($file, $chunkSize);
    $isLast = feof($file);

    if ($isLast) {
        // Last chunk - finish session
        $client->files->uploadSessionFinish(
            $session['session_id'],
            $offset,
            $chunk,
            ['path' => '/Videos/large-video.mp4', 'mode' => 'add']
        );
    } else {
        // Intermediate chunk
        $client->files->uploadSessionAppend(
            $session['session_id'],
            $offset,
            $chunk,
            false
        );
        $offset += strlen($chunk);
    }
}
fclose($file);
```

#### Downloading Files

[](#downloading-files)

```
// Download file
$file = $client->files->download('/Documents/report.pdf');
file_put_contents('local-report.pdf', $file['content']);
echo "Downloaded file size: " . strlen($file['content']) . " bytes";

// Download specific revision
$file = $client->files->download('/Documents/report.pdf', 'rev123abc');

// Download folder as ZIP
$zip = $client->files->downloadZip('/Documents/Project');
file_put_contents('project.zip', $zip['content']);

// Get temporary download link (valid for 4 hours)
$link = $client->files->getTemporaryLink('/Documents/report.pdf');
echo "Temporary link: " . $link['link'];

// Export file (e.g., Google Docs to PDF)
$exported = $client->files->export('/Documents/google-doc.gdoc', 'pdf');
file_put_contents('exported.pdf', $exported['content']);
```

#### File and Folder Management

[](#file-and-folder-management)

```
// Create folder
$folder = $client->files->createFolder('/Projects/NewProject');
echo "Created folder: " . $folder['metadata']['path_display'];

// Create multiple folders at once
$result = $client->files->createFolderBatch([
    '/Projects/Project1',
    '/Projects/Project2',
    '/Projects/Project3'
], false, false);

// Move file/folder
$moved = $client->files->move('/old/path.txt', '/new/path.txt');
echo "Moved to: " . $moved['metadata']['path_display'];

// Copy file/folder
$copied = $client->files->copy('/source.txt', '/destination.txt');

// Delete file/folder (to trash)
$client->files->delete('/path/to/delete.txt');

// Permanently delete (bypass trash)
$client->files->permanentlyDelete('/path/to/file.txt');

// Restore file to previous revision
$restored = $client->files->restore('/path/to/file.txt', 'rev123abc');

// Get file revision history
$revisions = $client->files->listRevisions('/Documents/important.docx', 'path', 100);
foreach ($revisions['entries'] as $rev) {
    echo "Revision: {$rev['rev']}, date: {$rev['client_modified']}\n";
}
```

#### Search and Listing

[](#search-and-listing)

```
// List folder contents
$result = $client->files->listFolder('/Documents');
foreach ($result['entries'] as $entry) {
    if ($entry['.tag'] === 'folder') {
        echo "Folder: " . $entry['name'] . "\n";
    } else {
        echo "File: " . $entry['name'] . " (" . $entry['size'] . " bytes)\n";
        echo "  Modified: " . $entry['client_modified'] . "\n";
    }
}

// List recursively
$result = $client->files->listFolder('', true);

// Continue listing with cursor (pagination)
if ($result['has_more']) {
    $more = $client->files->listFolderContinue($result['cursor']);
}

// Complete listing of large folder with pagination
$allEntries = [];
$result = $client->files->listFolder('/BigFolder');
$allEntries = array_merge($allEntries, $result['entries']);

while ($result['has_more']) {
    $result = $client->files->listFolderContinue($result['cursor']);
    $allEntries = array_merge($allEntries, $result['entries']);
}
echo "Total items: " . count($allEntries);

// Search files
$results = $client->files->search(
    'invoice',           // query
    '/Documents',        // path
    100,                 // max results
    'relevance',         // order by
    'active',            // file status
    null,                // filename only
    ['pdf', 'docx'],     // file extensions
    ['documents']        // file categories
);

foreach ($results['matches'] as $match) {
    $file = $match['metadata']['metadata'];
    echo "Found: {$file['name']} in {$file['path_display']}\n";
}

// Continue search with cursor
if ($results['has_more']) {
    $moreResults = $client->files->searchContinue($results['cursor']);
}

// Get file metadata
$metadata = $client->files->getMetadata('/Documents/file.txt', true);
echo "Modified: " . $metadata['client_modified'];
echo "Size: " . $metadata['size'] . " bytes";
echo "ID: " . $metadata['id'];

// Get metadata with media info
$metadata = $client->files->getMetadata('/Photos/vacation.jpg', true);
if (isset($metadata['media_info'])) {
    echo "Dimensions: {$metadata['media_info']['metadata']['dimensions']['width']}x";
    echo "{$metadata['media_info']['metadata']['dimensions']['height']}";
}
```

#### Thumbnails and Previews

[](#thumbnails-and-previews)

```
// Get thumbnail
$thumb = $client->files->getThumbnail(
    '/Photos/vacation.jpg',
    'jpeg',      // format: 'jpeg' or 'png'
    'w256h256',  // size: w32h32, w64h64, w128h128, w256h256, w480h320, w640h480, w960h640, w1024h768, w2048h1536
    'strict'     // mode: 'strict', 'bestfit', 'fitone_bestfit'
);
file_put_contents('thumb.jpg', $thumb['content']);

// Get preview
$preview = $client->files->getPreview('/Documents/presentation.pptx');
file_put_contents('preview.pdf', $preview['content']);

// Get thumbnails in batch
$thumbs = $client->files->getThumbnailBatch([
    [
        'path' => '/Photos/img1.jpg',
        'format' => 'jpeg',
        'size' => 'w128h128',
        'mode' => 'strict'
    ],
    [
        'path' => '/Photos/img2.jpg',
        'format' => 'jpeg',
        'size' => 'w128h128',
        'mode' => 'strict'
    ],
]);

foreach ($thumbs['entries'] as $entry) {
    if ($entry['.tag'] === 'success') {
        $thumbnail = $entry['thumbnail'];
        file_put_contents('thumb_' . basename($entry['metadata']['name']), $thumbnail);
    }
}
```

### Sharing

[](#sharing)

#### Shared Links

[](#shared-links)

```
// Create shared link
$link = $client->sharing->createSharedLinkWithSettings('/Documents/report.pdf', [
    'requested_visibility' => ['.tag' => 'public'],
    'audience' => ['.tag' => 'public'],
    'access' => ['.tag' => 'viewer'],
]);
echo "Share URL: " . $link['url'];

// Create link with password and expiration
$link = $client->sharing->createSharedLinkWithSettings('/Documents/secret.pdf', [
    'link_password' => 'mypassword123',
    'expires' => '2024-12-31T23:59:59Z',
]);

// List all shared links
$links = $client->sharing->listSharedLinks();

// Get shared link metadata
$metadata = $client->sharing->getSharedLinkMetadata('https://www.dropbox.com/...');

// Modify shared link settings
$updated = $client->sharing->modifySharedLinkSettings(
    'https://www.dropbox.com/...',
    ['requested_visibility' => ['.tag' => 'password']]
);

// Revoke shared link
$client->sharing->revokeSharedLink('https://www.dropbox.com/...');
```

#### Folder Sharing

[](#folder-sharing)

```
// Share a folder
$shared = $client->sharing->shareFolder('/Projects/TeamProject', null, false);
$folderId = $shared['shared_folder_id'];

// Add members to shared folder
$client->sharing->addFolderMember($folderId, [
    [
        'member' => ['.tag' => 'email', 'email' => 'colleague@example.com'],
        'access_level' => ['.tag' => 'editor'],
    ],
], false, 'Please review this project');

// List folder members
$members = $client->sharing->listFolderMembers($folderId);

// Update member permissions
$client->sharing->updateFolderMember(
    $folderId,
    ['.tag' => 'email', 'email' => 'colleague@example.com'],
    'viewer'
);

// Remove folder member
$client->sharing->removeFolderMember(
    $folderId,
    ['.tag' => 'email', 'email' => 'colleague@example.com'],
    true  // leave a copy
);

// List shared folders
$folders = $client->sharing->listFolders(100);

// Mount shared folder
$client->sharing->mountFolder($folderId);

// Unmount shared folder
$client->sharing->unmountFolder($folderId);

// Unshare folder
$client->sharing->unshareFolder($folderId, false);
```

#### File Sharing

[](#file-sharing)

```
// Add file members
$client->sharing->addFileMember(
    '/Documents/contract.pdf',
    [
        [
            'member' => ['.tag' => 'email', 'email' => 'client@example.com'],
            'access_level' => ['.tag' => 'viewer'],
        ],
    ],
    'Please review and sign',
    false,
    'viewer'
);

// List file members
$members = $client->sharing->listFileMembers('/Documents/contract.pdf');

// Remove file member
$client->sharing->removeFileMember(
    '/Documents/contract.pdf',
    ['.tag' => 'email', 'email' => 'client@example.com']
);
```

#### Image Hosting with Direct Links

[](#image-hosting-with-direct-links)

Convert Dropbox shared links to direct links for embedding images in HTML, Markdown, or other content. This is perfect for hosting images for blogs, portfolios, or documentation.

```
// Convert existing shared link to direct link
$sharedLink = 'https://www.dropbox.com/s/abcd1234/image.jpg?dl=0';

// Method 1: Using userusercontent (recommended - cleaner URLs)
$directLink = $client->sharing->convertToDirectLink($sharedLink);
// Returns: https://dl.dropboxusercontent.com/s/abcd1234/image.jpg

// Method 2: Using raw parameter
$directLink = $client->sharing->convertToDirectLink($sharedLink, 'raw');
// Returns: https://www.dropbox.com/s/abcd1234/image.jpg?raw=1

// Create a new shared link and convert it immediately
$result = $client->sharing->createDirectLink('/Photos/vacation.jpg');
echo "Direct URL: " . $result['direct_url'];

// Use in HTML
echo '';

// Use in Markdown
echo '![Vacation](' . $result['direct_url'] . ')';

// Create password-protected direct link with expiration
$result = $client->sharing->createDirectLink(
    '/Photos/private.jpg',
    [
        'link_password' => 'mypassword123',
        'expires' => '2024-12-31T23:59:59Z',
    ]
);

// Batch convert multiple links
$links = [
    'https://www.dropbox.com/s/abc123/img1.jpg?dl=0',
    'https://www.dropbox.com/s/def456/img2.png?dl=0',
];

foreach ($links as $link) {
    $directLink = $client->sharing->convertToDirectLink($link);
    echo $directLink . "\n";
}

// Create image gallery
$photos = $client->files->listFolder('/Photos');
$gallery = [];

foreach ($photos['entries'] as $photo) {
    if ($photo['.tag'] === 'file' && preg_match('/\.(jpg|jpeg|png|gif)$/i', $photo['name'])) {
        $linkData = $client->sharing->createDirectLink($photo['path_display']);
        $gallery[] = [
            'name' => $photo['name'],
            'url' => $linkData['direct_url'],
        ];
    }
}

// Display gallery
foreach ($gallery as $image) {
    echo '' . "\n";
}
```

**Laravel Example:**

```
use Tigusigalpa\Dropbox\Facades\Dropbox;

// Convert link
$directLink = Dropbox::sharing()->convertToDirectLink($sharedLink);

// Upload and get direct link
$file = $request->file('image');
$content = file_get_contents($file->getRealPath());
Dropbox::files()->upload('/Images/' . $file->getClientOriginalName(), $content);

$result = Dropbox::sharing()->createDirectLink('/Images/' . $file->getClientOriginalName());
return response()->json(['url' => $result['direct_url']]);
```

**Benefits:**

- ✅ No need for external image hosting services
- ✅ Direct embedding in HTML, Markdown, forums, etc.
- ✅ Reliable CDN delivery via Dropbox infrastructure
- ✅ Support for password protection and expiration dates
- ✅ Two conversion methods for different use cases

### Users and Account

[](#users-and-account)

```
// Get current account info
$account = $client->users->getCurrentAccount();
echo "Account ID: " . $account['account_id'];
echo "Name: " . $account['name']['display_name'];
echo "Email: " . $account['email'];
echo "Country: " . $account['country'];

// Get another user's account info
$user = $client->users->getAccount('dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc');

// Get multiple users' info
$users = $client->users->getAccountBatch([
    'dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc',
    'dbid:AAH1234567890abcdefghijklmnopqrst',
]);

// Get space usage
$space = $client->users->getSpaceUsage();
echo "Used: " . $space['used'] . " bytes\n";
echo "Allocated: " . $space['allocation']['allocated'] . " bytes\n";
$percentage = ($space['used'] / $space['allocation']['allocated']) * 100;
echo "Usage: " . number_format($percentage, 2) . "%\n";

// Check feature availability
$features = $client->users->getFeaturesValues([
    'paper_as_files',
    'file_locking',
]);
```

### File Requests

[](#file-requests)

```
// Create file request
$request = $client->fileRequests->create(
    'Upload your documents',
    '/File Requests/Documents',
    '2024-12-31T23:59:59Z',  // deadline
    true,                     // open
    'Please upload all required documents for the application'
);
echo "File request URL: " . $request['url'];

// Get file request
$request = $client->fileRequests->get('oaCAVmEyrqYnkZX9955Y');

// List all file requests
$requests = $client->fileRequests->list(1000);

// Update file request
$updated = $client->fileRequests->update('oaCAVmEyrqYnkZX9955Y', [
    'title' => 'Updated Title',
    'open' => false,
]);

// Delete file requests
$client->fileRequests->delete(['oaCAVmEyrqYnkZX9955Y']);

// Delete all closed file requests
$client->fileRequests->deleteAllClosed();

// Count file requests
$count = $client->fileRequests->count();
echo "Total file requests: " . $count['file_request_count'];
```

### Paper Documents

[](#paper-documents)

```
// Create Paper document
$doc = $client->paper->docsCreate(
    'Meeting NotesDiscussion points...',
    'html'
);
$docId = $doc['doc_id'];

// Download Paper document
$content = $client->paper->docsDownload($docId, 'markdown');
file_put_contents('notes.md', $content['content']);

// Update Paper document
$client->paper->docsUpdate(
    $docId,
    'Updated NotesNew content...',
    'html',
    'append',
    1
);

// Get Paper document metadata
$metadata = $client->paper->docsGetMetadata($docId);

// List Paper documents
$docs = $client->paper->docsList('docs_accessed', 'modified', 'descending', 100);

// Share Paper document
$client->paper->docsUsersAdd($docId, [
    [
        'member' => ['.tag' => 'email', 'email' => 'team@example.com'],
        'permission_level' => ['.tag' => 'edit'],
    ],
]);

// List users with access
$users = $client->paper->docsUsersList($docId, 100);

// Remove users
$client->paper->docsUsersRemove($docId, [
    ['.tag' => 'email', 'email' => 'team@example.com'],
]);

// Delete Paper document
$client->paper->docsPermanentlyDelete($docId);
```

### Batch Operations

[](#batch-operations)

```
// Copy multiple files
$job = $client->files->copyBatch([
    ['from_path' => '/file1.txt', 'to_path' => '/backup/file1.txt'],
    ['from_path' => '/file2.txt', 'to_path' => '/backup/file2.txt'],
]);

// Check batch job status
$status = $client->files->copyBatchCheck($job['async_job_id']);

// Move multiple files
$job = $client->files->moveBatch([
    ['from_path' => '/old/file1.txt', 'to_path' => '/new/file1.txt'],
    ['from_path' => '/old/file2.txt', 'to_path' => '/new/file2.txt'],
]);

// Delete multiple files
$job = $client->files->deleteBatch(['/file1.txt', '/file2.txt', '/file3.txt']);
```

### Save Files from URL

[](#save-files-from-url)

```
// Save file from URL
$job = $client->files->saveUrl('/Downloads/image.jpg', 'https://example.com/image.jpg');

// Check save URL job status
$status = $client->files->saveUrlCheckJobStatus($job['async_job_id']);

if ($status['.tag'] === 'complete') {
    echo "File saved successfully!";
}
```

OAuth 2.0 Authorization
-----------------------

[](#oauth-20-authorization)

### Authorization URL

[](#authorization-url)

```
use Tigusigalpa\Dropbox\DropboxClient;

// Generate authorization URL
$authUrl = DropboxClient::getAuthorizationUrl(
    'your_app_key',
    'https://your-app.com/callback',
    'random_state_string',  // CSRF protection
    ['files.content.write', 'files.content.read']  // optional scopes
);

// Redirect user to authorization URL
header('Location: ' . $authUrl);
```

### Exchange Code for Token

[](#exchange-code-for-token)

```
// In your callback route
$code = $_GET['code'];
$state = $_GET['state'];

// Verify state parameter (CSRF protection)
if ($state !== $_SESSION['oauth_state']) {
    die('Invalid state parameter');
}

// Exchange code for access token
$tokenData = DropboxClient::getAccessToken(
    $code,
    'your_app_key',
    'your_app_secret',
    'https://your-app.com/callback'
);

// Store tokens securely
$accessToken = $tokenData['access_token'];
$refreshToken = $tokenData['refresh_token'] ?? null;

// Create client with new token
$client = new DropboxClient($accessToken);
```

### Laravel OAuth Example

[](#laravel-oauth-example)

```
// routes/web.php
Route::get('/dropbox/auth', [DropboxController::class, 'redirectToDropbox']);
Route::get('/dropbox/callback', [DropboxController::class, 'handleCallback']);

// app/Http/Controllers/DropboxController.php
use Tigusigalpa\Dropbox\DropboxClient;

class DropboxController extends Controller
{
    public function redirectToDropbox()
    {
        $state = Str::random(40);
        session(['dropbox_state' => $state]);

        $url = DropboxClient::getAuthorizationUrl(
            config('dropbox.app_key'),
            config('dropbox.redirect_uri'),
            $state
        );

        return redirect($url);
    }

    public function handleCallback(Request $request)
    {
        if ($request->state !== session('dropbox_state')) {
            abort(403, 'Invalid state');
        }

        $tokenData = DropboxClient::getAccessToken(
            $request->code,
            config('dropbox.app_key'),
            config('dropbox.app_secret'),
            config('dropbox.redirect_uri')
        );

        // Store tokens for the user
        auth()->user()->update([
            'dropbox_access_token' => encrypt($tokenData['access_token']),
            'dropbox_refresh_token' => encrypt($tokenData['refresh_token'] ?? null),
        ]);

        return redirect('/dashboard')->with('success', 'Dropbox connected!');
    }
}
```

### Refresh Token

[](#refresh-token)

```
// Refresh access token when expired
$newTokenData = DropboxClient::refreshAccessToken(
    $refreshToken,
    'your_app_key',
    'your_app_secret'
);

$newAccessToken = $newTokenData['access_token'];

// Update client token
$client->setAccessToken($newAccessToken);
```

Error Handling
--------------

[](#error-handling)

```
use Tigusigalpa\Dropbox\Exceptions\DropboxException;

try {
    $result = $client->files->upload('/test.txt', 'content');
} catch (DropboxException $e) {
    echo "Error: " . $e->getMessage() . "\n";
    echo "Status Code: " . $e->getCode() . "\n";

    // Get detailed error information
    $response = $e->getResponse();
    if ($response) {
        echo "Error Summary: " . $e->getErrorSummary() . "\n";
        echo "Error Tag: " . $e->getErrorTag() . "\n";
        print_r($response);
    }
}
```

Advanced Examples
-----------------

[](#advanced-examples)

### Custom HTTP Client Configuration

[](#custom-http-client-configuration)

```
use GuzzleHttp\Client as GuzzleClient;
use Tigusigalpa\Dropbox\DropboxClient;

// Create custom Guzzle client
$guzzle = new GuzzleClient([
    'timeout' => 60,
    'verify' => true,
    'proxy' => 'http://proxy.example.com:8080',
]);

// Note: Currently the package creates its own Guzzle instance
// For custom configuration, you may need to extend the DropboxClient class
```

### Working with Cursors (Pagination)

[](#working-with-cursors-pagination)

```
// List all files in a large folder
$cursor = null;
$allFiles = [];

do {
    if ($cursor === null) {
        $result = $client->files->listFolder('/LargeFolder');
    } else {
        $result = $client->files->listFolderContinue($cursor);
    }

    $allFiles = array_merge($allFiles, $result['entries']);
    $cursor = $result['cursor'];
} while ($result['has_more']);

echo "Total files: " . count($allFiles);
```

### Monitoring Folder Changes

[](#monitoring-folder-changes)

```
// Get initial cursor
$cursor = $client->files->listFolderGetLatestCursor('/MonitoredFolder', true);
$cursorValue = $cursor['cursor'];

// Later, check for changes
$changes = $client->files->listFolderLongpoll($cursorValue, 30);

if ($changes['changes']) {
    // Get the actual changes
    $result = $client->files->listFolderContinue($cursorValue);

    foreach ($result['entries'] as $entry) {
        echo "Changed: " . $entry['name'] . "\n";
    }
}
```

Performance and Optimization
----------------------------

[](#performance-and-optimization)

### Efficient File Operations

[](#efficient-file-operations)

- **Chunked uploads** — large files are split into chunks (default 4MB, configurable) to avoid memory and timeout issues
- **Batch endpoints** — copy, move, delete up to 1000 files in a single API call
- **Persistent connections** — Guzzle keeps connections alive between requests
- **Stream-based downloads** — files are not loaded entirely into memory

### Caching Strategies

[](#caching-strategies)

```
// Cache folder listings to reduce API calls
$cacheKey = 'dropbox_folder_' . md5($path);
$contents = Cache::remember($cacheKey, 3600, function() use ($client, $path) {
    return $client->files->listFolder($path);
});

// Cache shared links
$linkCache = Cache::remember('dropbox_link_' . $fileId, 86400, function() use ($client, $path) {
    return $client->sharing->createSharedLinkWithSettings($path);
});
```

### Rate Limiting

[](#rate-limiting)

Dropbox API has rate limits. When you hit them, the SDK throws an exception with code 429:

```
try {
    $result = $client->files->upload($path, $content);
} catch (DropboxException $e) {
    if ($e->getCode() === 429) {
        // Rate limited - wait and retry
        $retryAfter = $e->getResponse()['retry_after'] ?? 60;
        sleep($retryAfter);
        $result = $client->files->upload($path, $content);
    }
}
```

Testing
-------

[](#testing)

Run the test suite:

```
composer test
```

Run tests with coverage:

```
composer test:coverage
```

API Reference
-------------

[](#api-reference)

For complete API documentation, visit:

- [Dropbox HTTP API Documentation](https://www.dropbox.com/developers/documentation/http/documentation)
- [Dropbox API Explorer](https://dropbox.github.io/dropbox-api-v2-explorer/)

Common Use Cases
----------------

[](#common-use-cases)

### Backup System

[](#backup-system)

```
// Backup local files to Dropbox
$backupFolder = '/Backups/' . date('Y-m-d');
$client->files->createFolder($backupFolder);

$files = glob('/var/www/app/storage/backups/*.sql');
foreach ($files as $file) {
    $content = file_get_contents($file);
    $client->files->upload(
        $backupFolder . '/' . basename($file),
        $content
    );
}
```

### File Sync

[](#file-sync)

```
// Sync local folder with Dropbox
$localPath = '/local/documents';
$remotePath = '/Documents';

$localFiles = new RecursiveIteratorIterator(
    new RecursiveDirectoryIterator($localPath)
);

foreach ($localFiles as $file) {
    if ($file->isFile()) {
        $relativePath = str_replace($localPath, '', $file->getPathname());
        $content = file_get_contents($file->getPathname());

        $client->files->upload(
            $remotePath . $relativePath,
            $content,
            'overwrite'
        );
    }
}
```

### Image Gallery

[](#image-gallery)

```
// Create image gallery with thumbnails
$photos = $client->files->listFolder('/Photos');

foreach ($photos['entries'] as $photo) {
    if ($photo['.tag'] === 'file') {
        // Get thumbnail
        $thumb = $client->files->getThumbnail(
            $photo['path_display'],
            'jpeg',
            'w256h256'
        );

        // Save thumbnail
        file_put_contents(
            'thumbs/' . $photo['name'],
            $thumb['content']
        );

        // Create shared link for full image
        $link = $client->sharing->createSharedLinkWithSettings(
            $photo['path_display']
        );

        echo '';
    }
}
```

Package Structure
-----------------

[](#package-structure)

### Core Components

[](#core-components)

```
dropbox-php/
├── config/
│   └── dropbox.php             # Laravel configuration
├── examples/
│   ├── basic-usage.php         # Standalone PHP usage examples
│   ├── laravel-usage.php       # Laravel integration examples
│   └── oauth-flow.php          # OAuth 2.0 flow implementation
├── src/
│   ├── Endpoints/              # API endpoint implementations
│   │   ├── Check.php           # API health checks
│   │   ├── FileRequests.php    # File request operations
│   │   ├── Files.php           # File/folder operations (40+ methods)
│   │   ├── Paper.php           # Dropbox Paper operations
│   │   ├── Sharing.php         # Sharing and collaboration (30+ methods)
│   │   └── Users.php           # User account operations
│   ├── Exceptions/
│   │   └── DropboxException.php # Custom exception class
│   ├── Facades/
│   │   └── Dropbox.php         # Laravel facade
│   ├── DropboxClient.php       # Main client class
│   └── DropboxServiceProvider.php # Laravel service provider
└── tests/                      # PHPUnit tests

```

### Usage Patterns

[](#usage-patterns)

**Standalone PHP:**

```
$client = new DropboxClient($accessToken);
$result = $client->files->upload('/path/file.txt', $content);
```

**Laravel Facade:**

```
use Tigusigalpa\Dropbox\Facades\Dropbox;
$result = Dropbox::files()->upload('/path/file.txt', $content);
```

**Laravel Dependency Injection:**

```
public function upload(DropboxClient $dropbox) {
    $result = $dropbox->files->upload('/path/file.txt', $content);
}
```

Testing
-------

[](#testing-1)

The package ships with:

- Unit tests for core functionality
- Integration test examples
- GitHub Actions CI/CD workflow
- PHPUnit configuration

Run tests:

```
composer test
```

Run tests with coverage:

```
composer test:coverage
```

### Setup for Testing

[](#setup-for-testing)

1. Fork the repository
2. Clone your fork:

    ```
    git clone https://github.com/YOUR_USERNAME/dropbox-php.git
    cd dropbox-php
    ```
3. Install dependencies:

    ```
    composer install
    ```
4. Create a `.env` file with your Dropbox credentials for testing:

    ```
    DROPBOX_ACCESS_TOKEN=your_test_token
    ```

Contributing
------------

[](#contributing)

Contributions are welcome. Please follow these guidelines:

### Coding Standards

[](#coding-standards)

- Follow PSR-12 coding standards
- Write clear, descriptive commit messages
- Add PHPDoc blocks for all public methods
- Use type hints for parameters and return types
- Keep methods focused and single-purpose

### Pull Request Process

[](#pull-request-process)

1. Create a new branch for your feature:

    ```
    git checkout -b feature/your-feature-name
    ```
2. Make your changes and commit:

    ```
    git commit -m "Add feature: description"
    ```
3. Push to your fork:

    ```
    git push origin feature/your-feature-name
    ```
4. Create a Pull Request on GitHub
5. Ensure all tests pass and code follows standards

### Adding New Features

[](#adding-new-features)

When adding new Dropbox API endpoints:

1. Create or update the appropriate endpoint class in `src/Endpoints/`
2. Add comprehensive PHPDoc comments
3. Include links to official Dropbox API documentation
4. Add usage examples to README.md
5. Write tests for the new functionality

### Reporting Issues

[](#reporting-issues)

- Use the GitHub issue tracker
- Include PHP version, Laravel version (if applicable)
- Provide code examples that reproduce the issue
- Include error messages and stack traces

Troubleshooting Guide
---------------------

[](#troubleshooting-guide)

### Common Issues and Solutions

[](#common-issues-and-solutions)

#### Authentication Errors

[](#authentication-errors)

**Problem:** "Invalid access token" error

**Solutions:**

- Verify your access token is correct and not expired
- For OAuth tokens, implement refresh token logic
- Check that your app has the required permissions/scopes
- Ensure the token hasn't been revoked in Dropbox App Console

```
// Check token validity
try {
    $account = $client->users->getCurrentAccount();
    echo "Token is valid for: " . $account['email'];
} catch (DropboxException $e) {
    if ($e->getCode() === 401) {
        // Token invalid - need to refresh or re-authenticate
        $newToken = DropboxClient::refreshAccessToken($refreshToken, $appKey, $appSecret);
    }
}
```

#### File Upload Failures

[](#file-upload-failures)

**Problem:** Upload fails for large files or times out

**Solutions:**

- Use chunked upload for files larger than 150MB
- Increase PHP `max_execution_time` and `memory_limit`
- Implement retry logic for network failures
- Check file path format (must start with /)

```
// Robust upload with retry
$maxRetries = 3;
$attempt = 0;

while ($attempt < $maxRetries) {
    try {
        $result = $client->files->upload($path, $content);
        break;
    } catch (DropboxException $e) {
        $attempt++;
        if ($attempt >= $maxRetries) {throw $e;}
        sleep(2 ** $attempt); // Exponential backoff
    }
}
```

#### Path Errors

[](#path-errors)

**Problem:** "Path not found" or "Malformed path" errors

**Solutions:**

- Ensure paths start with `/` (e.g., `/Documents/file.txt`)
- Use proper encoding for special characters
- Check that parent folders exist before creating files
- Verify case sensitivity (Dropbox paths are case-insensitive but case-preserving)

```
// Ensure parent folder exists
$filePath = '/Documents/Reports/2024/report.pdf';
$parentPath = dirname($filePath);

try {
    $client->files->getMetadata($parentPath);
} catch (DropboxException $e) {
    // Parent doesn't exist - create it
    $client->files->createFolder($parentPath);
}

$client->files->upload($filePath, $content);
```

#### Laravel Integration Issues

[](#laravel-integration-issues)

**Problem:** Service provider not loading or facade not working

**Solutions:**

- Clear Laravel cache: `php artisan cache:clear`
- Clear config cache: `php artisan config:clear`
- Republish config: `php artisan vendor:publish --tag=dropbox-config --force`
- Verify `.env` variables are set correctly
- Check that package is in `composer.json` require section

```
# Complete Laravel reset
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
composer dump-autoload
```

### Debug Mode

[](#debug-mode)

Enable detailed error logging:

```
try {
    $result = $client->files->upload($path, $content);
} catch (DropboxException $e) {
    // Log detailed error information
    Log::error('Dropbox API Error', [
        'message' => $e->getMessage(),
        'code' => $e->getCode(),
        'error_summary' => $e->getErrorSummary(),
        'error_tag' => $e->getErrorTag(),
        'response' => $e->getResponse(),
        'trace' => $e->getTraceAsString()
    ]);
}
```

Frequently Asked Questions (FAQ)
--------------------------------

[](#frequently-asked-questions-faq)

### General Questions

[](#general-questions)

**Q: Is this library production-ready?**

A: Yes. It has error handling, test coverage, and follows PSR-12. Used in production by several projects.

**Q: What's the difference between this and the official Dropbox SDK?**

A: This package targets PHP 8.1+, ships with Laravel integration (service provider, facade, config), and provides a simpler method-based API. The official SDK is more low-level.

**Q: Can I use this without Laravel?**

A: Yes, works as a standalone PHP library. Laravel integration is optional.

**Q: Does it support Dropbox Business/Team accounts?**

A: Yes, both personal and business accounts are supported. Use team-scoped access tokens for team operations.

### Technical Questions

[](#technical-questions)

**Q: What's the maximum file size I can upload?**

A: Up to 350GB with chunked upload. Files under 150MB can use the simple `upload()` method. Larger files go through upload sessions.

**Q: How do I handle rate limiting?**

A: The SDK throws `DropboxException` with code 429. Implement exponential backoff as shown in the troubleshooting section.

**Q: Can I upload files from URLs directly to Dropbox?**

A: Yes, `saveUrl()` tells Dropbox to fetch the file from a URL on its side.

**Q: How do I get a permanent link to a file?**

A: `createSharedLinkWithSettings()` gives you a permanent link. For short-lived links (4 hours), use `getTemporaryLink()`.

**Q: Does it support Dropbox Paper?**

A: Yes, the Paper endpoint covers creating, editing, sharing, and deleting Paper documents.

**Q: How do I handle file conflicts?**

A: Pass the `mode` parameter: `'add'` (fail if exists), `'overwrite'` (replace), or `'update'` (update a specific revision).

### Security Questions

[](#security-questions)

**Q: How should I store access tokens?**

A: Don't store tokens in plain text. Use `encrypt()` in Laravel, environment variables, or a secrets manager. In production, use OAuth with refresh tokens.

**Q: Is it safe to use in multi-tenant applications?**

A: Yes. Create a separate `DropboxClient` per user with their own token. Don't share tokens between users.

**Q: How do I revoke access?**

A: Revoke tokens via the Dropbox App Console or build a revocation flow in your app settings.

Best Practices
--------------

[](#best-practices)

### Security Best Practices

[](#security-best-practices)

1. **Never hardcode access tokens** - Use environment variables or secure configuration management
2. **Implement OAuth 2.0 flow** - For production applications, use proper OAuth instead of generated tokens
3. **Use refresh tokens** - Implement token refresh logic to maintain long-term access
4. **Validate user input** - Sanitize file paths and names before passing to API
5. **Implement rate limiting** - Add application-level rate limiting to prevent API abuse
6. **Log security events** - Track authentication failures and suspicious activities
7. **Use HTTPS only** - Ensure all callbacks and webhooks use HTTPS
8. **Scope permissions appropriately** - Request only the OAuth scopes your application needs

### Development Best Practices

[](#development-best-practices)

1. **Use type hints** - Leverage PHP 8.1+ type system for better code quality
2. **Handle exceptions properly** - Always wrap API calls in try-catch blocks
3. **Implement retry logic** - Handle transient failures with exponential backoff
4. **Cache API responses** - Reduce API calls by caching folder listings and metadata
5. **Use batch operations** - Process multiple files efficiently with batch endpoints
6. **Test with real data** - Create a test Dropbox account for development
7. **Monitor API usage** - Track API call volumes to stay within rate limits
8. **Version your code** - Use semantic versioning and maintain changelog

### Performance Best Practices

[](#performance-best-practices)

1. **Use chunked uploads** - For files over 150MB, always use upload sessions
2. **Implement pagination** - Handle large folder listings with cursor-based pagination
3. **Stream large downloads** - Don't load entire files into memory
4. **Optimize search queries** - Use specific paths and filters to reduce result sets
5. **Leverage cursors** - Use `listFolderContinue()` for efficient pagination
6. **Batch thumbnail requests** - Get multiple thumbnails in one API call
7. **Use temporary links** - For public file access, temporary links are faster than downloads
8. **Implement queue workers** - Process large file operations asynchronously in Laravel

### Laravel-Specific Best Practices

[](#laravel-specific-best-practices)

```
// Use queued jobs for large operations
class UploadToDropboxJob implements ShouldQueue
{
    public function handle(DropboxClient $dropbox)
    {
        $dropbox->files->upload($this->path, $this->content);
    }
}

// Use events for file operations
event(new FileUploadedToDropbox($filePath, $metadata));

// Implement middleware for Dropbox webhooks
Route::post('/dropbox/webhook', [DropboxWebhookController::class, 'handle'])
    ->middleware('verify.dropbox.signature');
```

Comparison with Official Dropbox SDK
------------------------------------

[](#comparison-with-official-dropbox-sdk)

FeatureThis SDKOfficial Dropbox SDKPHP Version8.1+7.4+Laravel IntegrationBuilt-in (provider, facade)ManualAPI v2 CoverageAll major endpointsAll endpointsDocumentationExamples + API referenceAPI referenceType SafetyFull type hintsPartialError HandlingDedicated exception classBasic exceptionsChunked UploadBuilt-in helpersManual implementationBatch OperationsSupportedSupportedOAuth 2.0 HelpersIncludedManual### Migration from Other Libraries

[](#migration-from-other-libraries)

Method names map closely to the Dropbox HTTP API documentation:

```
// Old library (example)
$dropbox->uploadFile('/path', $content);

// This SDK
$client->files->upload('/path', $content);

// Old library
$dropbox->getMetadata('/path');

// This SDK
$client->files->getMetadata('/path');
```

Method names follow the Dropbox API naming, so the [official HTTP docs](https://www.dropbox.com/developers/documentation/http/documentation) serve as a reference.

Real-World Use Cases
--------------------

[](#real-world-use-cases)

### E-Commerce Platform

[](#e-commerce-platform)

Store product images, invoices, and customer documents:

```
// Upload product images with organized structure
$productId = 12345;
$imagePath = "/products/{$productId}/images/main.jpg";
$client->files->upload($imagePath, $imageContent);

// Generate shareable link for product image
$link = $client->sharing->createSharedLinkWithSettings($imagePath);
$product->image_url = $link['url'];
```

### Document Management System

[](#document-management-system)

Manage corporate documents with version control:

```
// Upload document with metadata
$result = $client->files->upload(
    "/documents/contracts/{$contractId}.pdf",
    $pdfContent,
    'add'
);

// Track revisions
$revisions = $client->files->listRevisions($result['path_display']);

// Share with specific users
$client->sharing->addFileMember($result['path_display'], [
    ['member' => ['.tag' => 'email', 'email' => 'legal@company.com']]
]);
```

### Automated Backup System

[](#automated-backup-system)

Create scheduled backups of critical data:

```
// Laravel scheduled task
protected function schedule(Schedule $schedule)
{
    $schedule->call(function (DropboxClient $dropbox) {
        $backupPath = '/backups/' . date('Y-m-d-H-i-s');
        $dropbox->files->createFolder($backupPath);

        // Backup database
        $dbBackup = Storage::get('backups/database.sql');
        $dropbox->files->upload("{$backupPath}/database.sql", $dbBackup);

        // Backup files
        $filesBackup = Storage::get('backups/files.tar.gz');
        $dropbox->files->upload("{$backupPath}/files.tar.gz", $filesBackup);
    })->daily();
}
```

### Media Gallery Application

[](#media-gallery-application)

Build a photo gallery with thumbnails:

```
// Upload photos and generate thumbnails
foreach ($photos as $photo) {
    $path = "/gallery/{$albumId}/{$photo->name}";
    $client->files->upload($path, $photo->content);

    // Get thumbnail
    $thumb = $client->files->getThumbnail($path, 'jpeg', 'w256h256');
    Storage::put("thumbnails/{$photo->id}.jpg", $thumb['content']);

    // Create public link
    $link = $client->sharing->createSharedLinkWithSettings($path);
    $photo->public_url = $link['url'];
}
```

### Collaborative Workspace

[](#collaborative-workspace)

Enable team collaboration with shared folders:

```
// Create project workspace
$projectFolder = "/projects/{$projectName}";
$client->files->createFolder($projectFolder);

// Share with team
$shared = $client->sharing->shareFolder($projectFolder);

// Add team members
foreach ($teamMembers as $member) {
    $client->sharing->addFolderMember($shared['shared_folder_id'], [[
        'member' => ['.tag' => 'email', 'email' => $member->email],
        'access_level' => ['.tag' => $member->role === 'admin' ? 'editor' : 'viewer']
    ]]);
}
```

Changelog
---------

[](#changelog)

### Version 1.0.0 - 2024-12-20

[](#version-100---2024-12-20)

**Added:**

- Initial release
- Full Dropbox API v2 support
- Files endpoint with complete file/folder operations
- Sharing endpoint for collaboration features
- Users endpoint for account management
- File Requests endpoint
- Paper endpoint for Dropbox Paper documents
- Check endpoint for API health checks
- Laravel 8-12 integration with service provider and facade
- OAuth 2.0 flow helpers
- Comprehensive documentation and examples
- PHPUnit test suite
- GitHub Actions CI/CD workflow

**Features:**

- Upload/download files with chunked upload support
- File and folder management (copy, move, delete, search)
- Shared links and folder sharing
- Batch operations support
- Thumbnail generation
- File preview and export
- Space usage tracking
- Error handling with detailed exceptions

Security
--------

[](#security)

If you discover any security-related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [Igor Sazonov](https://github.com/tigusigalpa)
- [All Contributors](https://github.com/tigusigalpa/dropbox-php/contributors)

License
-------

[](#license)

MIT License (MIT). Please see [LICENSE](LICENSE) file for more information.

Links
-----

[](#links)

- [GitHub Repository](https://github.com/tigusigalpa/dropbox-php)
- [Packagist](https://packagist.org/packages/tigusigalpa/dropbox-php)
- [Dropbox API Documentation](https://www.dropbox.com/developers/documentation/http/documentation)
- [Dropbox Developer Portal](https://www.dropbox.com/developers)
- [Dropbox App Console](https://www.dropbox.com/developers/apps)
- [Dropbox API Explorer](https://dropbox.github.io/dropbox-api-v2-explorer/)

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance85

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~53 days

Total

2

Last Release

87d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/76c3a1d93c3213a8a22b4b637708d8b66a1ba3a5252624046cae7683a198b3a8?d=identicon)[tigusigalpa](/maintainers/tigusigalpa)

---

Top Contributors

[![tigusigalpa](https://avatars.githubusercontent.com/u/2721390?v=4)](https://github.com/tigusigalpa "tigusigalpa (6 commits)")

---

Tags

cloud-storagedropboxdropbox-apidropbox-sdklaravelphpsdkapilaravelsdkfile downloaddropboxfile-uploadcloud-storagefile-sharing

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/tigusigalpa-dropbox-php/health.svg)

```
[![Health](https://phpackages.com/badges/tigusigalpa-dropbox-php/health.svg)](https://phpackages.com/packages/tigusigalpa-dropbox-php)
```

###  Alternatives

[openai-php/laravel

OpenAI PHP for Laravel is a supercharged PHP API client that allows you to interact with the Open AI API

3.7k7.6M74](/packages/openai-php-laravel)[smodav/mpesa

M-Pesa API implementation

16363.7k1](/packages/smodav-mpesa)[mozex/anthropic-laravel

Anthropic PHP for Laravel is a supercharged PHP API client that allows you to interact with the Anthropic API

71226.4k1](/packages/mozex-anthropic-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)