README

Введение

Неофициальное 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

leonied7 / yandex-disk-api

Maintainers

Details

README

Введение

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

Требования

Установка

Composer

Тесты

Описание

Введение

Возможности

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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