PHP библиотека к API Яндекс диска

Введение

Неофициальное PHP SDK для сервиса Яндекс.Диск

Список изменений

27/12/2018

полностью переписана логика работы с api
упращена работы с SDK
обновлено README

Требования

PHP 5.6+
Расширение php_curl

Установка

Composer

composer require leonied7/yandex-disk-api:dev-master

пример подключения:

require_once __DIR__ . "/vendor/autoload.php";

Тесты

Запуск тестов из корня библиотеки:

vendor/phpunit/phpunit/phpunit --configuration phpunit.xml

Описание

Введение

SDK для работы использует WebDAV API Яднекс Диска. Для работы необходим OAuth-токен(например, AQACc1234LDE2f_123UIbouFHzfxxcvDI), который необходимо получить самостоятельно:

зарегистрировать приложение и самостоятельно получить токен https://oauth.yandex.ru/

OAuth-токен должен иметь разрешённые права "Яндекс.Диск WebDAV API"

Возможности

Работа с папками на Яндекс.Диске (создание, копирование, перемещение, удаление, публикация и т.д.)
Работа с файлами на Яндекс.Диске (создание, загрузка, скачивание, копирование, перемещение, удаление, публикация и т.д.)
Потоковая загрузка и скачивание файлов
Фрагментное скачивание файлов

Инициализация

use \Leonied7\Yandex\Disk;
$yandexDisk = new Disk('OAuth-токен');

Использование

\Leonied7\Yandex\Disk - используется для работы с диском, запрашивает основную информацию о диске и клиенте, а так же помогает работать с файлами и папками
\Leonied7\Yandex\Disk\Item\File - используется для работы с файлом
```
/** @var \Leonied7\Yandex\Disk\Item\File $file */
$yandexDisk->file('/path/to/file/');
```

\Leonied7\Yandex\Disk\Item\Directory - используется для работы с директорией

/** @var \Leonied7\Yandex\Disk\Item\Directory $directory */
$directory = $yandexDisk->directory('/path/to/directory/');

Используемые объекты

\Leonied7\Yandex\Disk\Entity\Result - после выполнения любого запроса к Яндекс.Диску можно получить информацию о результате
\Leonied7\Yandex\Disk\Entity\Collection
- \Leonied7\Yandex\Disk\Collection\PropertyCollection - коллекция свойств
- \Leonied7\Yandex\Disk\Collection\PropertyFail - коллекция ошибочных свойств свойств
\Leonied7\Yandex\Disk\Model\Property
- \Leonied7\Yandex\Disk\Property\Immutable - неизменяемое свойство
- \Leonied7\Yandex\Disk\Property\Mutable - изменяемое свойство
\Leonied7\Yandex\Disk\Item\Item
- \Leonied7\Yandex\Disk\Item\File - объект файла
- \Leonied7\Yandex\Disk\Item\Directory - объект директории
\Leonied7\Yandex\Disk\Model\Decorator
- \Leonied7\Yandex\Disk\Decorator\CurrentElement - возвращает данные о элементе с входных путём
- \Leonied7\Yandex\Disk\Decorator\CurrentElementCollection - возвращает данные о коллекции элемента с входных путём
- \Leonied7\Yandex\Disk\Decorator\CurrentElementCollectionItem - возвращает данные о свойстве коллекции элемента с входных путём
- \Leonied7\Yandex\Disk\Decorator\CurrentElementCollectionItemValue - возвращает значение свойства коллекции элемента с входных путём
- \Leonied7\Yandex\Disk\Decorator\CurrentElementFailCollection - возвращает массив ошибочных коллекций элемента с входных путём
- \Leonied7\Yandex\Disk\Decorator\ExplodeData - возвращает разбитую строку на массив типа "ключ => значение"
\Leonied7\Yandex\Disk\Model\Stream
- \Leonied7\Yandex\Disk\Stream\File - осуществляет работу с потоком файла, используется для записи/чтения файла

Использование

Запрос информации о пользователе

$info = $yandexDisk->getInfo();
//вернёт примерно следующий результат
Array
(
    [uid] => xxxxxxxxx
    [login] => login
    [fio] => fio
    [firstname] => firstname
    [lastname] => lastname
    [upload_concurrency] => 5
    [datasync_db_prefix] => 
    [is_b2b] => false
)

Запрос свободного/занятого места

/** @var \Leonied7\Yandex\Disk\Collection\PropertyCollection $spaceCollection */
$spaceCollection = $yandexDisk->spaceInfo();
//поиск в коллекции свойство с имененем 'quota-available-bytes'
/** @var \Leonied7\Yandex\Disk\Property\Immutable $available */
$available = $spaceCollection->find('quota-available-bytes');
echo $available->getValue(); //свободное места

/** @var \Leonied7\Yandex\Disk\Property\Immutable $used */
$used = $spaceCollection->find('quota-used-bytes');
echo $used->getValue(); //занятое места

Загрузка файла (Применимо только для файлов)

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$file->upload(new Disk\Stream\File('/path/to/local/file', Disk\Stream\File::MODE_READ)); //bool

Скачивание файла (Применимо только для файлов)

SDK поддерживает скачивание файлов несколькими способами:

Потоковое скачивание

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$file->download(new Disk\Stream\File('/path/to/local/file', Disk\Stream\File::MODE_WRITE)); //bool

Потоковое скачивание частями

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
//скачивание первых 5 байт
$file->download(new Disk\Stream\File('/path/to/local/file', Disk\Stream\File::MODE_WRITE), 0, 5); //bool
//скачивание с 6 байта до конца 
$file->download(new Disk\Stream\File('/path/to/local/file', Disk\Stream\File::MODE_WRITE_APPEND), 6); //bool

Скачивание без потока

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$file->download(); //bool
// получение последнего результата запроса
$result = Disk\Collection\ResultList::getInstance()->getLast();
file_put_contents('/path/to/local/file', $result->getActualResult());

Получение превью картинок (Применимо только для файлов)

Первым параметром передаётся размер превью, может быть применён любой из документации

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$file->getPreview('S', new Disk\Stream\File('/path/to/local/file/', Disk\Stream\File::MODE_WRITE));

Превью может быть получена потоком, либо без потока

Создание директории (Применимо только для директорий)

/** @var Disk\Item\Directory $directory */
$directory = $yandexDisk->directory('/path/to/directory/');
$directory->create(); // bool

Получение содержимого директории (Применимо только для директорий)

/** @var Disk\Item\Directory $directory */
$directory = $yandexDisk->directory('/path/to/directory/');
/** @var Disk\Item\Item[] $arChild */
$arChild = $directory->getChildren();
/** @var Disk\Item\Item $child */
foreach ($arChild as $child) {
    if ($child->isDirectory()) {
        /** @var Disk\Item\Directory $directory */
        $directory = $child;
        //работа с директорией
    } else {
        /** @var Disk\Item\File $file */
        $file = $child;
        //работа с файлом
    }
}

Так же первым параметром можно передать объект типа \Leonied7\Yandex\Disk\Collection\PropertyCollection для получения свойств для всех элементов.

Так же 2 и 3 параметром можно указать offset(смещение) и amount(количество) - для получение только необходимого диапозона элементов.

Проверка существования элемента (Применимо для файла/директории)

Пример написан для файла, но метод так же применим для директории

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$file->has(); // bool

Так как для проверки существования используется метод запроса свойств, то по умолчанию Яндекс.Диск отдаёт свойства. При вызове метода has() можно передать объект типа \Leonied7\Yandex\Disk\Collection\PropertyCollection.

Пример:

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$collection = new Disk\Collection\PropertyCollection();
$collection
    ->add('getcontenttype', Disk\Model\Property::IMMUTABLE_NAMESPACES['dav']) //запрос типа содержимого
    ->add('displayname', Disk\Model\Property::IMMUTABLE_NAMESPACES['dav']) //запрос имени содержимого
    ->add('myprop', 'mynamespace'); //полученис своего свойства
$file->has($collection); // bool

Если объект не передаётся, то выбираются все доступные свойства автоматически.

Получить пришедшие свойства можно следущим образом:

/** @var Disk\Collection\PropertyCollection $collection */
$collection = $file->getProperties();

или

/** @var Disk\Collection\PropertyCollection $collection */
$collection1 = Disk\Collection\ResultList::getInstance()->getLast()->getResult();

Результат будет хранить только успешно полученные свойства.

Для получения ошибочных свойств

/** @var Disk\Collection\PropertyFail[] $failCollections */
$failCollections = Disk\Collection\ResultList::getInstance()->getLast()->getDecorateResult(new Disk\Decorator\CurrentElementFailCollection($file->getPath()));
foreach ($failCollections as $failCollection) {
    $failCollection->getStatus(); //получение статуса ответа от Яндекс.Диска для коллекции
    //так же можно применять такие же методы что и для Disk\Property\Immutable
}

Копирование элемента (Применимо для файла/директории)

Пример написан для файла, но метод так же применим для директории

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$file->copy('/path/to/copy/'); // bool

По стандарту если файл уже существует по назначения, то он будет перезаписан. Для запрета перезаписи, необходимо передать вторым параметром false

Перемещение элемента (Применимо для файла/директории)

Пример написан для файла, но метод так же применим для директории

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$file->move('/path/to/move/'); // bool

По стандарту если файл уже существует по назначения, то он будет перезаписан. Для запрета перезаписи, необходимо передать вторым параметром false

Удаление элемента (Применимо для файла/директории)

Пример написан для файла, но метод так же применим для директории

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$file->delete(); // bool

Загрузка свойств элемента (Применимо для файла/директории)

Пример написан для файла, но метод так же применим для директории

/** @var \Yandex\Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
//создаём коллекцию и добавляем в неё 3 свойства
$propertyCollection = new \Yandex\Disk\Collection\Property();
$propertyCollection
    ->add('myprop', 'mynamespace')
    ->add('propmy', 'mynamespace')
    ->add('propprop', 'mynamespace');
    
/** @var \Yandex\Disk\Collection\Property $loadCollection */
$loadCollection = $file->loadProperties($propertyCollection);
/** @var \Yandex\Disk\Collection\Property $property */
foreach ($loadCollection as $property) {
    // работаем со свойствами
}

Ранее успешно загруженные свойства можно получить с помощью $file->getProperties();

Результат будет хранить только успешно полученные свойства.

Для получения ошибочных свойств

/** @var \Yandex\Disk\Collection\PropertyFail[] $convertedResult */
$failCollections = $file->getLastResult()->getDecorateResult(new \Yandex\Disk\Decorator\CurrentElementFailCollection($file->getPath()));
foreach ($failCollections as $failCollection) {
    $failCollection->getStatus() //получение статуса ответа от Яндекс.Диска
}

полное описание ошибочный коллекций \Leonied7\Yandex\Disk\Collection\PropertyFail

Получение существующих свойств (Применимо для файла/директории)

Пример написан для файла, но метод так же применим для директории

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
/** @var Disk\Collection\PropertyCollection $propertyCollection */
$propertyCollection = $file->getExistProperties();

Внимание!!! свойства приходят без значений и не могут быть получены через $file->getProperties();

Изменение свойства элемента (Применимо для файла/директории)

Пример написан для файла, но метод так же применим для директории

Есть два способа изменения свойств у элемента:

Изменение переданных свойств

Добавляем свойства myprop и propmy с namespace mynamespace значения foo и bar соответственно. Удаляем свойство propprop

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$propertyCollection = new Disk\Collection\PropertyCollection();
$propertyCollection
    ->add('myprop', 'mynamespace', 'foo')
    ->add('propmy', 'mynamespace', 'bar')
    ->add('propprop', 'mynamespace');

$file->changeProperties($propertyCollection); // bool

Сохранение заранее полученных свойств

Неименяемые свойства не сохраняются

Загружаем свойства myprop, propmy, propprop, quota-available-bytes

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$propertyCollection = new Disk\Collection\PropertyCollection();
$propertyCollection
    ->add('myprop', 'mynamespace')
    ->add('propmy', 'mynamespace')
    ->add('quota-available-bytes', Disk\Model\Property::IMMUTABLE_NAMESPACES['dav'])
    ->add('propprop', 'mynamespace');

/** @var Disk\Collection\PropertyCollection $loadCollection */
$loadCollection = $file->loadProperties($propertyCollection);

В загруженной коллекции есть свойства двух видов, изменяемые и неименяемые

Свойства приходят неизменяемыми для встроенных свойств Яндекс.Диска. Например quota-available-bytes будет неизменяемым

Для получения только изменяемых свойств коллекции

/** @var Disk\Property\Mutable $property */
foreach ($loadCollection->getChangeable() as $property) {
    $property->setValue('baz'); //устанавливаем новое значение
}

Так же можно узнать можно ли изменять свойтво через метод у свойства canChanged()

// добавляем новое свойство
$loadCollection->add('newprop', 'mynamespace', 'bar');
// добавляем неизменяемое свойств (свойство не будет сохранятся)
$loadCollection->add('immutable', Disk\Model\Property::IMMUTABLE_NAMESPACES['dav'], 'immut');

После этого сохраняем измененные значения

$file->saveProperties();

Публикация элемента (Применимо для файла/директории)

Пример написан для файла, но метод так же применим для директории

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$file->startPublish(); // bool
//получение публичной ссылки
Disk\Collection\ResultList::getInstance()->getLast()->getResult(); // string

Закрытие публикации элемента (Применимо для файла/директории)

Пример написан для файла, но метод так же применим для директории

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$file->stopPublish(); // bool

Проверка публикации элемента (Применимо для файла/директории)

Пример написан для файла, но метод так же применим для директории

/** @var Disk\Item\File $file */
$file = $yandexDisk->file('/path/to/file/');
$file->checkPublish(); // bool
//получение публичной ссылки
Disk\Collection\ResultList::getInstance()->getLast()->getResult(); // string