Dropbox PHP SDK

Актуальная PHP библиотека для Dropbox API v2 с комплексной совместимостью с Laravel (версии 8-12). Библиотека обеспечивает элегантный и удобный интерфейс для использования функциональных возможностей облачного хранения и командной работы Dropbox.

🌐 Язык: Русский | English

🔗 GitHub Repository: https://github.com/tigusigalpa/dropbox-php

Содержание

• Особенности
• Поддерживаемые эндпоинты
• Требования
• Установка
• Быстрый старт
• Подробные примеры использования
  • Работа с файлами
  • Совместный доступ
  • Пользователи и аккаунт
  • File Requests
  • Paper документы
  • Пакетные операции
• OAuth 2.0 авторизация
• Использование в Laravel
• Обработка ошибок
• Продвинутые примеры
• Структура пакета
• Тестирование
• Contributing
• Changelog
• Лицензия

Ключевые возможности

• ✅ Комплексная реализация Dropbox API v2 - Полная поддержка всех главных эндпоинтов
• 🚀 Поддержка фреймворка Laravel - Нативная интеграция с Laravel версий 8, 9, 10, 11 и 12
• 🎯 Актуальные стандарты PHP - Разработан с использованием возможностей PHP 8.1+ и передовых практик
• 📦 Независимость от фреймворка - Превосходно функционирует в окружении без Laravel
• 🔐 Аутентификация OAuth 2.0 - Интегрированные утилиты для OAuth workflow
• 📝 Расширенная документация - Глубокие примеры и полная документация API
• 🧪 Тщательное тестирование - Содержит всеобъемлющие PHPUnit тесты
• 🎨 Элегантный интерфейс - Удобный дизайн с цепочкой методов
• ⚡ Чанковая передача файлов - Обработка загрузки крупных файлов через разбиение
• 🔄 Массовые операции - Оптимизированные возможности пакетной обработки

Охват API эндпоинтов

• Files - Обработка загрузки, скачивания, перемещения, копирования, удаления, поиска и организации файлов/папок
• Sharing - Генерация общих ссылок, контроль прав доступа к папкам/файлам, обеспечение командной работы
• Users - Получение данных аккаунта, использования хранилища и доступных возможностей
• File Requests - Создание и администрирование форм сбора файлов
• Paper - Разработка, изменение и управление документами Dropbox Paper
• Check - Проверка статуса подключения к API и работоспособности сервиса

Системные требования

• PHP версии 8.1 или новее
• Guzzle HTTP библиотека 7.0 или выше
• Laravel 8.0 или позднее (опционально, требуется только для интеграции с Laravel)

Руководство по установке

Установка через менеджер пакетов Composer:

Настройка для Laravel

Библиотека автоматически регистрирует свой service provider и компоненты facade.

Экспортируйте конфигурационный файл:

Настройте учетные данные Dropbox API в файле

Начало работы

Получение токена доступа

1. Зарегистрируйте приложение Dropbox в Dropbox App Console
2. Выберите тип приложения и необходимые разрешения
3. Создайте access token через интерфейс настроек приложения

Для production окружений используйте OAuth 2.0 workflow (обратитесь к разделу OAuth 2.0 авторизация).

Базовая реализация (Standalone PHP)

Реализация в Laravel

Всесторонние примеры использования

Операции с файлами

Методы загрузки файлов

Передача крупных файлов (чанковая загрузка)

Операции скачивания файлов

Управление файлами и директориями

Поиск и листинг

Превью и миниатюры

Совместный доступ

Общие ссылки

Совместный доступ к папкам

Совместный доступ к файлам

Пользователи и аккаунт

File Requests

Paper документы

Пакетные операции

Сохранение файлов из URL

OAuth 2.0 авторизация

URL авторизации

Обмен кода на токен

Пример OAuth в Laravel

Обновление токена

Обработка ошибок

Продвинутые примеры

Настройка HTTP клиента

Работа с курсорами (пагинация)

Мониторинг изменений в папке

Тестирование

Запустить тестовый набор:

Запустить тесты с покрытием:

Документация API

Для всесторонней справки по API обратитесь к:

• Документация Dropbox HTTP API
• Обозреватель Dropbox API

Практические сценарии применения

Автоматизированное резервное копирование

Синхронизация директорий

Построитель фотогалереи

Архитектура библиотеки

Основные компоненты

dropbox-php/
├── config/
│   └── dropbox.php             # Конфигурация Laravel
├── examples/
│   ├── basic-usage.php         # Примеры standalone использования
│   ├── laravel-usage.php       # Примеры интеграции с Laravel
│   └── oauth-flow.php          # Реализация OAuth 2.0 flow
├── src/
│   ├── Endpoints/              # Реализация API эндпоинтов
│   │   ├── Check.php           # Проверка API
│   │   ├── FileRequests.php    # Операции с file requests
│   │   ├── Files.php           # Операции с файлами/папками (40+ методов)
│   │   ├── Paper.php           # Операции с Dropbox Paper
│   │   ├── Sharing.php         # Совместный доступ (30+ методов)
│   │   └── Users.php           # Операции с пользователями
│   ├── Exceptions/
│   │   └── DropboxException.php # Кастомное исключение
│   ├── Facades/
│   │   └── Dropbox.php         # Laravel facade
│   ├── DropboxClient.php       # Главный клиент
│   └── DropboxServiceProvider.php # Laravel service provider
└── tests/                      # PHPUnit тесты

Паттерны реализации

Чистый PHP:

Паттерн Laravel Facade:

Паттерн внедрения зависимостей Laravel:

Фреймворк тестирования

Библиотека включает:

• Unit тесты для основной функциональности
• Примеры интеграционного тестирования
• GitHub Actions CI/CD конвейер
• PHPUnit конфигурацию

Выполнение тестов:

Выполнение тестов с отчетами о покрытии:

Настройка тестового окружения

1. Форкните репозиторий

2. Клонируйте вашу копию:

3. Установите необходимые зависимости:

4. Настройте файл

   .env
   с учетными данными Dropbox для тестирования:

Руководство по участию

Вклад в проект приветствуется! Пожалуйста, придерживайтесь следующих рекомендаций:

Стандарты кода

• Соблюдайте соглашения кодирования PSR-12
• Составляйте ясные, содержательные сообщения коммитов
• Включайте PHPDoc документацию для всех публичных методов
• Применяйте объявления типов для параметров и возвращаемых значений
• Поддерживайте сфокусированные методы с единственной ответственностью

Процесс внесения изменений

1. Создайте ветку для функции:

2. Реализуйте изменения и зафиксируйте:

3. Отправьте в ваш репозиторий:

4. Отправьте Pull Request на GitVerse

5. Проверьте, что все тесты проходят и код соответствует стандартам

Разработка функций

При реализации новых эндпоинтов Dropbox API:

1. Создайте или модифицируйте соответствующий класс эндпоинта в
   src/Endpoints/
2. Включите всестороннюю PHPDoc документацию
3. Ссылайтесь на официальную документацию Dropbox API
4. Предоставьте примеры использования в README.md
5. Разработайте тесты для новой функциональности

Отчеты об ошибках

• Используйте трекер проблем GitVerse
• Укажите версию PHP, версию Laravel (если применимо)
• Предоставьте образцы кода, демонстрирующие проблему
• Приложите сообщения об ошибках и трассировки стека

Changelog

Версия 1.0.0 - 2024-12-20

Представлено:

• Первый публичный релиз
• Полная реализация Dropbox API v2
• Эндпоинт Files с комплексным набором операций с файлами/папками
• Эндпоинт Sharing для возможностей совместной работы
• Эндпоинт Users для администрирования аккаунта
• Функциональность эндпоинта File Requests
• Эндпоинт Paper для управления документами Dropbox Paper
• Эндпоинт Check для проверки подключения к API
• Совместимость с Laravel 8-12 через service provider и facade
• Утилиты аутентификации OAuth 2.0
• Обширная документация с практическими примерами
• Фреймворк тестирования PHPUnit
• Автоматизация CI/CD через GitHub Actions

Возможности:

• Загрузка/скачивание файлов с поддержкой чанковой передачи
• Операции с файлами и директориями (дублирование, перемещение, удаление, поиск)
• Генерация общих ссылок и совместная работа с папками
• Обработка пакетных операций
• Создание миниатюр изображений
• Предпросмотр документов и конвертация форматов
• Мониторинг квоты хранилища
• Обработка исключений с детальной информацией об ошибках

Раскрытие уязвимостей

При обнаружении уязвимостей безопасности, пожалуйста, свяжитесь напрямую по адресу sovletig@gmail.com, а не через публичный трекер проблем.

Авторы

• Igor Sazonov
• Все участники

Лицензия

MIT License (MIT). Подробная информация в файле LICENSE.

Ресурсы

• Репозиторий GitVerse
• Пакет Packagist
• Документация Dropbox API
• Портал разработчиков Dropbox
• Консоль приложений Dropbox
• Обозреватель Dropbox API

Разработано с ❤️ Igor Sazonov