leonied7/yandex-disk-api

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

Введение

Неофициальное PHP SDK для сервиса Яндекс.Диск, _(*1)

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

27/12/2018 * полностью переписана логика работы с api * упращена работы с SDK * обновлено README, _(*2)

Требования

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

Установка

Composer

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

пример подключения:, _(*3)

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

Тесты

Запуск тестов из корня библиотеки:, _(*4)

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

Описание

Введение

SDK для работы использует WebDAV API Яднекс Диска. Для работы необходим OAuth-токен(например, AQACc1234LDE2f_123UIbouFHzfxxcvDI), который необходимо получить самостоятельно: * зарегистрировать приложение и самостоятельно получить токен https://oauth.yandex.ru/, _(*5)

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

Возможности

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

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

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

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

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

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

• \Leonied7\Yandex\Disk\Entity\Result - после выполнения любого запроса к Яндекс.Диску можно получить информацию о результате, _(*7)

• \Leonied7\Yandex\Disk\Entity\Collection, _(*8)

  • \Leonied7\Yandex\Disk\Collection\PropertyCollection - коллекция свойств
  • \Leonied7\Yandex\Disk\Collection\PropertyFail - коллекция ошибочных свойств свойств

• \Leonied7\Yandex\Disk\Model\Property, _(*9)

  • \Leonied7\Yandex\Disk\Property\Immutable - неизменяемое свойство
  • \Leonied7\Yandex\Disk\Property\Mutable - изменяемое свойство

• \Leonied7\Yandex\Disk\Item\Item, _(*10)

  • \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 поддерживает скачивание файлов несколькими способами: 1. Потоковое скачивание, _(*11)

```php
/** @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
```

2. Потоковое скачивание частями, _(*12)

```php
/** @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
```

3. Скачивание без потока, _(*13)

```php
/** @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());
```

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

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

/** @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));

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

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

/** @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 для получения свойств для всех элементов., _(*16)

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

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

Пример написан для файла, но метод так же применим для директории, _(*18)

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

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

Пример:, _(*20)

/** @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

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

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

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

или, _(*23)

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

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

Для получения ошибочных свойств, _(*25)

/** @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
}

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

Пример написан для файла, но метод так же применим для директории, _(*26)

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

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

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

Пример написан для файла, но метод так же применим для директории, _(*28)

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

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

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

Пример написан для файла, но метод так же применим для директории, _(*30)

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

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

Пример написан для файла, но метод так же применим для директории, _(*31)

/** @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();, _(*32)

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

Для получения ошибочных свойств, _(*34)

/** @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, _(*35)

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

Пример написан для файла, но метод так же применим для директории, _(*36)

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

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

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

Пример написан для файла, но метод так же применим для директории, _(*38)

Есть два способа изменения свойств у элемента: 1. Изменение переданных свойств, _(*39)

Добавляем свойства `myprop` и `propmy` с namespace `mynamespace` значения `foo` и `bar` соответственно. Удаляем свойство `propprop`
```php
/** @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
```

2. Сохранение заранее полученных свойств, _(*40)

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

Загружаем свойства `myprop`, `propmy`, `propprop`, `quota-available-bytes`
```php
/** @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` будет неизменяемым

Для получения только изменяемых свойств коллекции
```php
/** @var Disk\Property\Mutable $property */
foreach ($loadCollection->getChangeable() as $property) {
    $property->setValue('baz'); //устанавливаем новое значение
}
```
> Так же можно узнать можно ли изменять свойтво через метод у свойства `canChanged()`
```php
// добавляем новое свойство
$loadCollection->add('newprop', 'mynamespace', 'bar');
// добавляем неизменяемое свойств (свойство не будет сохранятся)
$loadCollection->add('immutable', Disk\Model\Property::IMMUTABLE_NAMESPACES['dav'], 'immut');
```

После этого сохраняем измененные значения
```php
$file->saveProperties();
```

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

Пример написан для файла, но метод так же применим для директории, _(*41)

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

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

Пример написан для файла, но метод так же применим для директории, _(*42)

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

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

Пример написан для файла, но метод так же применим для директории, _(*43)

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