Yandex

Введение

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

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

21/11/2022

• PHP 7.4, 8.0, 8.1

21/12/2020

• Начиная с 2.1 минимальная версия php 7.3
• zend-diactoros заменён на laminas-diactoros (laminas-zendframework-bridge)

23/08/2016

• метод upload поддерживает событие progress, слушатель принимает float значение в процентах.
• возвращена ранее удалённая опция disable_redirects.
• исправление грамматических ошибок в README.md

Требования

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

Внести свой вклад в развитие

Вы можете сообщить о найденных неточностях в работе SDK, приветствуется помощь в разработке. Чтобы начать помогать вести разработку Вам нужно создать fork репозитория ветки development, внесите изменения в код и отправьте pull request нам с изменениями в ветку development.

Установка

Поддерживается установка с помощью менеджера пакетов.

$ composer require arhitector/yandex dev-master

Или

$ php composer.phar require arhitector/yandex dev-master

Тесты

Вы можете не найти некоторых тестов - мы их не публикуем по причинам приватности.

$ composer test

1. Сервис Яндекс.Диск

1.1. Введение

PHP SDK для работы с Яндекс.Диском, в своей основе использует REST API диска. API диска для аунтификации использует OAuth-токен (например, 0c4181a7c2cf4521964a72ff57a34a07), который Вы должны получить самостоятельно:

• зарегистрировать приложение и самостоятельно получить токен https://oauth.yandex.ru
• или воспользоваться возможностями SDK, читайте о методе AccessToken::refreshAccessToken (RFC 6749#4.3.2. в скором времени, а возможно уже, будет отключен)

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

Ресурс - файл или папка на Яндекс.Диске. SDK определяет три состояния ресурса: публичный, закрытый, и тот который помещён в корзину.

1.1.1. Возможности

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

• Работа с файлами на Яндекс.Диске (получение информации, копирование, перемещение, загрузка, скачивание и т.д.)
• Работа с публичными ресурсами (публикация, скачивание, копирование на свой Яндекс.Диск, и т.п.)
• Работа с ресурсами в корзине (список файлов в корзине, очистка корзины, восстановление файла из корзины и прочее)
• Поддерживает события: 'operation', 'downloaded', 'uploaded', 'deleted'
• ~~Шифрование файлов (не поддерживается, используйте ветку 1.0)~~
• Получение ссылок DocViewer

возможно это не полный список

Плагины, дополнения, адаптеры

• адаптер yandex-disk-flysystem для thephpleague/flysystem (существующий адаптер WebDav хорош, но не позволяет публиковать ресурсы - тут эта возможность имеется).

1.1.2. Папки приложений

Приложения могут хранить на Диске пользователя собственные данные — например, настройки, сделанные этим пользователем или созданные им файлы. Чтобы запрашивать доступ к собственной папке на Диске, приложение следует зарегистрировать с правом "Доступ к папке приложения на Диске". Такое приложение сможет оперировать файлами только в рамках своей папки, если не получит также прав на общий доступ к Диску. SDK различает общий доступ и доступ приложения к собственной папке, префиксами "disk:/" и "app:/" соответственно. Тем не менее в информации о ресурсе пути указываются в схеме disk:/, с абсолютными путями к ресурсам, например "disk:/Приложения/МоёПервоеПриложение/photo.png".

1.1.3. Пример использования

// передать OAuth-токен зарегистрированного приложения.
$disk = new Arhitector\Yandex\Disk('OAuth-токен');

/**
 * Получить Объектно Ориентированное представление закрытого ресурса.
 * @var  Arhitector\Yandex\Disk\Resource\Closed $resource
 */
$resource = $disk->getResource('новый файл.txt');

// проверить сущестует такой файл на диске ?
$resource->has(); // вернет, например, false

// загрузить файл на диск под имененм "новый файл.txt".
$resource->upload(__DIR__.'/файл в локальной папке.txt');

// файл загружен, вывести информацию.
var_dump($resource->toArray())

// теперь удалить в корзину.
$removed = $resource->delete();

SDK вызывает исключения по каждой ситуации, следующий пример показывает как это можно использовать.

try
{
  try
  {
    /**
     * Получить закрытый ресурс
     * @var  Arhitector\Yandex\Disk\Resource\Closed $resource
     */
    $resource = $disk->getResource('новый файл.txt');

    // До этого момента запросов к Диску не было
    // Только сейчас был сделан запрос на получение информации о ресурсе к Яндекс.Диску
    // Вывести информацию. Когда ресурс не найден будет вызвано исключение NotFoundException
    $resource->toArray();
  }
  catch (Arhitector\Yandex\Client\Exception\NotFoundException $exc)
  {
    // Ресурс на Диске отсутствует, загрузить под именем 'новый файл.txt'
    $resource->upload(__DIR__.'/файл в локальной папке.txt');
  }

  // Теперь удалю, совсем.
  $file->delete(true);
}
catch (Arhitector\Yandex\Client\Exception\UnauthorizedException $exc)
{
	// Записать в лог, авторизоваться не удалось
	log($exc->getMessage());
}
catch (Exception $exc)
{
	// Что-то другое
}

1.2. Как подключиться к Яндекс.Диску

Обращение к Яндекс.Диску осуществляется через Arhitector\Yandex\Disk. После получения OAuth-токена, его (OAuth-токен) можно использовать следующим образом:

• Вариант 1. Инициализировать клиент.

Один и тот же OAuth-токен может быть использован для доступа к разным сервисам.

$client = new Arhitector\Yandex\Client\OAuth('OAuth-токен');

Инициализировать клиент Яндекс.Диска и передать $client.

$disk = new Arhitector\Yandex\Disk($client);

• Вариант 2. Инициализировать клиент Яндекс.Диска с передачей OAuth-токена в конструктор.

$disk = new Arhitector\Yandex\Disk('OAuth-токен');

• Вариант 3. Инициализировать клиент Яндекс.Диска без передачи OAuth-токена.

Вы можете установить или изменить OAuth-токен в ранее инициализированном объекте.

$client->setAccessToken('OAuth-токен');

Или изменить OAuth-токен для клиента Яндекс.Диска

$disk->setAccessToken('OAuth-токен');

На этом этапе есть несколько переменных, например $disk и $client, которые будут использованы далее в документации для отсылки к определённым объектам.

/**
 * @var Arhitector\Yandex\Client\OAuth  $client
 * @var Arhitector\Yandex\Disk          $disk
 */

Примечание: Arhitector\Yandex\Client\OAuth не является реализацией протокола OAuth 2.0.

1.2.1. Установить OAuth-токен

Устанавливает OAuth-токен для прохождения аунтификации на сервисах. Не все операции требуют OAuth-токен.

public $this OAuth::setAccessToken(string $token)

public $this Disk::setAccessToken(string $token)

Примеры

$disk->setAccessToken('0c4181a7c2cf4521964a72ff57a34a07');

или

$client->setAccessToken('0c4181a7c2cf4521964a72ff57a34a07');

1.2.2. Получить установленный OAuth-токен

Получает ранее установленный OAuth-токен или NULL.

public mixed OAuth::getAccessToken( void );

public mixed Disk::getAccessToken( void );

Примеры

$disk->getAccessToken(); // null

или

$client->getAccessToken(); // string '0c4181a7c2cf4521964a72ff57a34a07'

1.3. Работа с Яндекс.Диском

SDK различает три типа ресурсов: публичный, закрытый, и тот который помещён в корзину. Каждый из типов представлен своим объектом. Для любого типа ресурса доступна фильтрация (методы setMediaType, setType и т.д.) у каждого из типов свой набор возможных значений.

• Публичный ресурс, Arhitector\Yandex\Disk\Resource\Opened

• Ресурс доступный владельцу, Arhitector\Yandex\Disk\Resource\Closed

• Ресурс в корзине, Arhitector\Yandex\Disk\Resource\Removed

Введение

Существуют базовые методы получения всевозможного рода информации, которые доступны везде. Кроме прочего, поддерживаются обращения к фиктивным свойствам и работа с объектом как с массивом.

• Объект->свойство

$disk->total_space; // объём диска

$resource->size; // размер файла

• Объект['свойство']

$disk['free_space']; // свободное место

$resource['name']; // название файла/папки

1.3.1. Метод get

Получить значение по ключу.

public mixed Объект::get(string $index [, mixed $default = null])

$index - индекс/ключ, по которому получить значение (free_space, name и т.д.)

$default - значение по умолчанию, если такой индекс отсутствует - может принимать анонимную функцию, которая будет вызвана с текущим контекстом (Disk, Closed, и т.д.)

Примеры

// индекс total_space
$disk->get('total_space');

// custom_properties или FALSE если отсутствует
$resource->get('custom_properties', false);

 // вернёт результат 'any thing' анонимной функции 
$removedResource->get('property_123', function (Removed $resource) {
  return 'any thing';
});

1.3.2. Метод toArray

Получает содержимое всего контейнера в виде массива.

Примечание: метод не является рекурсивным, это означает, что вложенные ресурсы (например, файлы в папке) не будут преобразованы в массив, а результатом будет массив объектов т.е. массив ресурсов (файлы, папки), представленные своим объектом.

public array Объект::toArray([array $allowed = null])

$allowed - массив ключей, которые необходимо вернуть.

Примеры

// массив информация о Яндекс.Диске
$disk->toArray();

// получить только 
$disk->toArray(['total_space', 'free_space']);

// массив объектов
$collection->toArray();

// массив, информация о ресурсе
$resource->toArray();

1.3.3. Метод toObject

Получает содержимое всего контейнера в виде объекта.

Примечание: метод не является рекурсивным, это означает, что вложенные ресурсы (например, файлы в папке) не будут преобразованы в объект, а результатом будет коллекция объектов.

public stdClass Объект::toObj