README

非官方PHP SDK用于某些Yandex服务：Yandex.Disk服务。

变更记录

15/07/2024

PHP 8.0, 8.1, 8.2

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中发现的错误，欢迎帮助开发。要开始帮助开发，您需要创建分支development，修改代码，并将更改通过pull request发送到我们的development分支。

安装

支持使用包管理器安装。

$ composer require ufee/yandex-disk

测试

您可能找不到某些测试 - 我们出于隐私原因没有发布。

$ composer test

1. Yandex.Disk服务

1.1. 简介

用于操作Yandex.Disk的PHP SDK，其基础是磁盘的REST API。API使用OAuth-令牌进行认证（例如，0c4181a7c2cf4521964a72ff57a34a07），您需要自行获取

注册应用程序并自行获取令牌 https://oauth.yandex.ru
或利用SDK的功能，请参阅AccessToken::refreshAccessToken方法（RFC 6749#4.3.2. 在不久的将来，可能已经停止）

SDK仅与调试令牌一起工作。OAuth-令牌必须具有"Yandex.Диск REST API"的授权权限。

资源 - Yandex.Disk上的文件或文件夹。SDK定义了三种资源状态：公共、私有以及被放入回收站的。

1.1.1. 功能

主要功能

在Yandex.Disk上操作文件（获取信息、复制、移动、上传、下载等）
操作公共资源（发布、下载、复制到自己的Yandex.Disk等）
操作回收站资源（回收站中的文件列表、清空回收站、从回收站恢复文件等）
支持事件：'operation', 'downloaded', 'uploaded', 'deleted'
~~文件加密（不支持，请使用1.0版本分支）~~
获取DocViewer链接

可能这不是完整的列表

插件、扩展、适配器

适配器 yandex-disk-flysystem 用于 thephpleague/flysystem（现有的WebDav适配器很好，但不允许发布资源 - 这里提供了这一功能）。

1.1.2. 应用程序文件夹

应用程序可以在用户的磁盘上存储自己的数据，例如，用户通过应用程序创建的设置或文件。要请求对磁盘上自己的文件夹的访问，应用程序应注册具有"访问磁盘上的应用程序文件夹"权限。这样的应用程序只能在其文件夹内操作文件，除非它还获得了对磁盘的公共访问权限。SDK区分公共访问和应用程序对其自己的文件夹的访问，分别使用"disk:"和"app:"前缀。然而，在资源信息中，路径以disk:/方案指定，使用到资源的绝对路径，例如"disk:/Applications/MyFirstApp/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令牌后，可以使用以下方式使用它：

方案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等）调用（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 Объект::toObject([array $allowed = null])

$allowed - 获取这些键。

示例

$disk->toObject();

$collection->toObject();

$resource->toObject(['name', 'type']);

1.3.4 getIterator方法

获取迭代器。您可以使用SDK对象在循环中。

public ArrayIterator Объект::getIterator( void )

示例

$disk->getIterator();

$collection->getIterator();

$resource->items->getIterator();

例如，$resource是文件夹。获取此文件夹中的嵌套文件/文件夹。

foreach ($resource->items as $item)
{
  // $item объект ресурса `Resource\\*`, вложенный в папку.
}

1.3.5 count方法

计算数量。

public integer Объект::count( void )

返回实例的异步操作数量

Disk::count()

返回字段数量

Resource\*::count()

示例

// Возвращает количество асинхронных операций экземпляра.
$disk->count();

// в других случаях размер контейнера
$resource->items->count();

1.3.6 has和hasProperty方法

has方法

方法has的行为取决于上下文。它可以检查是否存在属性或是否存在雅虎.Диск上的资源。

注意：将来方法的行为可能会简化。

public bool Объект::has([string $key = NULL])

$key - 可选参数，索引。

带有参数的调用检查属性是否存在

$disk->has('total_space_123'); // false

$resource->has('name'); // true

不带参数的调用仅在资源上下文Resource\\*中受支持，并检查资源是否存在。

$resource->has(); // true

hasProperty方法

与has方法相同，但只执行一项操作——检查属性是否存在，并且仅在使用Resource\\*上下文时可用

public boolean Объект::hasProperty(string $key)

$key - 用于检查存在的索引/属性。

示例

$resource->hasProperty('custom_properties'); // false

1.3.7. 获取磁盘信息。

获取信息的方法在上文已描述。

$disk->toArray();

将返回一个数组，内容大致如此。方法 toObject 返回相应的对象。

array (size=5)
    'trash_size' => int 187017199
    'total_space' => float 14495514624
    'used_space' => float 14083430863
    'system_folders' => array (size=2)
        'applications' => string 'disk:/Приложения' (length=26)
        'downloads' => string 'disk:/Загрузки/' (length=23)
    'free_space' => float 412083761

方法 count 这里将返回发起的异步操作的数量。

$disk->count(); // int 0

count($disk); // int 5

方法 get 的可用键

trash_size - 桌面回收站大小（字节）。
total_space - 磁盘容量（字节）。
used_space - 已使用空间（字节）。
free_space - 可用空间（字节）。
system_folders - 包含系统文件夹路径的数组。

// метод get
$disk->get('total_space'); // float 14495514624

// объект->свойство
$disk->used_space; // float 14083430863

// объект['свойство']
$disk['system_folders'];

/* array (size=2)
'applications' => string 'disk:/Приложения' (length=26)
'downloads' => string 'disk:/Загрузки/' (length=23) */

// используем параметр $default
$disk->get('не существующее свойство', 'default value'); // string 'default value'

1.3.8. 处理受限资源。

通过方法 Disk::getResource 和 Disk::getResources 来处理磁盘上的资源，这些方法仅对磁盘的所有者可用。资源是否存在并不重要。区别在于，当资源存在时，可以请求资源的信息，否则将引发 NotFoundException 异常。实际上，对于尚未存在的资源，只能进行 upload 操作将其上传到磁盘，之后才能执行发布、删除等操作。

方法 Disk::getResource

获取特定资源的面向对象的表示。磁盘的所有者可以访问此类资源。

public Resource\Closed Disk::getResource(string $path [, int $limit = 20 [, int $offset = 0]])

$path - 新资源或已存在资源的路径。

$limit - 响应中的资源数量。

$offset - 偏移量。用于所有文件列表或如果资源是文件夹，则用于文件夹内资源的偏移量。

示例

获取资源对象。

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

$resource = $disk->getResource('disk:/путь от корня диска/до файла/или папки/название.txt');

从应用程序文件夹中获取资源对象。

/**
 * @var Arhitector\Yandex\Disk\Resource\Closed  $resource
 */
$resource = $disk->getResource('app:/название.txt', 100, 10);

可以在获取资源对象后通过方法 setLimit 和 setOffset 设置 $limit 和 $offset。

$resource = $disk->getResource('/', 10);

$resource = $disk->getResource('/', 10, 5);

$resource->setLimit(100);

$resource->setOffset(200);

方法 Disk::getResources，所有文件的列表。

获取文件夹、子文件夹等中的所有文件的列表。列表由 Arhitector\Yandex\Disk\Resource\Collection 对象表示。

public Resource\Collection Disk::getResources([, int $limit = 20 [, int $offset = 0]])

这里提供了过滤方法、基本获取信息方法和一系列其他方法。

示例

/**
 * Получить список всех файлов
 *
 * @var Disk\Resource\Collection  $collection
 */
$collection = $disk->getResources();

$disk->getResources(100, 15);

文件夹中的文件列表也由 Arhitector\Yandex\Disk\Resource\Collection 对象表示。

$resource->items; // object 'Arhitector\Yandex\Disk\Resource\Collection'

方法 getFirst

获取列表中的第一个资源。这可能是一个 Closed、Opened 或 Removed。

public mixed Collection::getFirst( void )

示例

$collection->getFirst(); // object 'Resource/Closed'

方法 getLast

集合方法，获取最后一个元素。

public mixed Collection::getLast( void )

示例

$collection->getLast(); // object 'Resource/Opened'

过滤方法

所有这些都在 API 端进行处理。对于集合，提供了以下方法

setLimit
setMediaType
setOffset
setPreviewCrop
setPreview
setSort

1.3.8.1. 检查资源是否存在

使用之前描述的 has 方法（无参数调用）可以检查资源是否存在于磁盘上。如果使用参数，则检查是否存在属性。

注意：将来此方法可能会简化。

示例

$resource->has();

$resource->has('name'); // проверить, есть ли 'name'

1.3.8.2. 获取资源信息

使用之前描述的基本获取信息方法进行。

示例

$resource->toObject();

$resource->get('items');

$resource->hasProperty('name');

$resource->has('type');

$resource->toArray(['name', 'type', 'size']);

$resource->size;

$resource['type'];

$resource->get('custom_properties', []);

1.3.8.3. 资源是文件/文件夹

存在 isFile 和 isDir 方法来处理这种情况。

public boolean Объект::isFile( void )

public boolean Объект::isDir( void )

示例

$resource->isFile(); // true

$resource->isDir(); // false

1.3.8.4. 资源是公开的/或仅对所有者可用

使用 isPublish 方法可以检查文件或文件夹是否公开。

public boolean Объект::isPublish( void )

示例

$resource->isPublish(); // false

// отрыть доступ к ресурсу
if ( ! $resource->isPublish())
{
  $resource->setPublish(true);
}

1.3.8.5. 磁盘上资源的路径

可以使用 getPath 方法来获取路径。此路径由 SDK 使用，虽然值可能与雅虎磁盘返回的值不同，但这种不匹配是完全正确的。

public string Объект::getPath( void )

示例

$resource->getPath(); // disk:/файл.txt

1.3.8.6. 为资源添加/删除元信息

添加的元信息存储在 "custom_properties" 属性中。对象的键和值的最大长度为 1024 个字节。值不应为 NULL。

public $this Closed::set(mixed $meta [, mixed $value = null])

$meta - 字符串或值数组。

$value - NULL 用于当 $meta 为字符串时删除特定的元信息。

示例

$resource->set('any', 'thing');

$resource->set([
  'any'   => 'thing',
  'thing' => 'any'
]);

$resource['any'] = 'thing';

$resource->any = 'thing';

删除信息

要删除元信息，需要将值设置为 NULL。

示例

$resource->set('any', null); // удалить 'any'

$resource->set('thing'); // удалить 'thing'

unset($resource['any']);

unset($resource->any);

方法 getProperty

与 "custom_properties" 属性一起工作，其中存储了添加的元信息。此方法类似于 get 方法。

注意：将来此方法可能会重命名。

public mixed Closed::getProperty(string $index [, mixed $default = null])

$index - 获取值的键。

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

示例

$resource->getProperty('any');

$resource->get('thing12141', 'значение по умолчанию'); // вернет значение по умолчанию

$resource->get('index', function (Resource\Closed $resource) {
  // анонимная функция будет вызвана с параметром
  // текущего контекста и значение по умолчанию
  // будет значение, возвращаемое этой функцией

  return 'значение по умолчанию';
});

Метод getProperties

Получает массив всей метаинформации.

public array Closed::getProperties( void )

示例

$resource->getProperties(); // array

// метод 'get' также может получать метаинформацию.
// получить всю доступную метаинформацию в виде массива
$resource->get('custom_properties', []);

// получение информации без использования метода 'getProperty'
$resource->get('custom_properties')['thing12141']

1.3.8.7. Удаление файла или папки

Удалить совсем или поместить файл или папку в корзину можно методом delete.

public mixed delete([bool $permanently = false])

$permanently - признак безвозвратного удаления. FALSE поместит ресурс в корзину (поведение по умолчанию).

Возвращаемые значения

boolean - результат выполнения.
Arhitector\Yandex\Disk\Operation - объект синхронной операции, если по мнению API Яндекс.Диска операция удаления длительная.
~~Arhitector\Yandex\Disk\Resource\Removed - объект ресурса в корзине (не поддерживается).~~

示例

$resource->delete(); // в корзину

$resource->delete(true); // удалить без помещения в корзину

1.3.8.8. Перемещение файла или папки

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

public mixed Closed::move(mixed $destionation [, $overwrite = FALSE] )

$destination - новое расположение ресурса. Может быть строкой или Resource\Closed.

$overwrite - boolean признак перезаписи, если по новому пути существует ресурс. TRUE перезапишет (поведение по умолчанию FALSE - не перезаписывать).

Возвращаемые значения

bool или объект Arhitector\Yandex\Disk\Operation

示例

$resource->move('/путь/до/файла.txt');

$resource->move('app:/новая папка', true);

$resource->move($resource2);

1.3.8.9. Создание папки

Если ресурс уже существует будет вызвано исключение AlreadyExists.

public $this Closed::create( void )

示例

$resource->create();

1.3.8.10. Публикация ресурса\Закрытие доступа

Открывает доступ к ресурсу из вне по публичной ссылке. Опубликованные ресурсы управляются своим объектом Arhitector\Yandex\Disk\Resource\Opened.

public mixed Closed::setPublish([bool $publish = true])

$publish - признак публичности, TRUE сделать ресурс публичным (поведение по умолчанию), FALSE отменить публикацию ресурса.

Возвращаемые значения

Arhitector\Yandex\Disk\Resource\Closed возвращается когда доступ закрыт.

Arhitector\Yandex\Disk\Resource\Opened возвращается если был открыт доступ к ресурсу.

У ресурса с открытым доступом существует дополнительная информация, такая как public_key или public_url. Также docviewer возвращает ссылку доступную всем из вне.

示例

$resource->setPublish(); // открывает доступ

$resource-setPublish(true); // открывает доступ

$resource->setPublish(false); // закрывает доступ

$resource->isPublish(); // true если ресурс с открытым доступом

$resource->public_url; // URL адрес

1.3.8.11. Скачивание файла

Метод download безопасен от переполнения памяти и может быть использован для скачивания файлов и папок (автоматически в виде zip-архива).

public bool Closed::download(mixed $destination [, bool $overwrite = false])

$destination - позволяет указать куда будет сохранён ресурс.

Поддерживаются следующие типы

string - путь, по которому будет записан ресурс.
resource - дескриптор файла, открытый на запись.
StreamInterface - объект на запись, реализующий PSR StreamInterface.

$overwrite - используется совместно с $destination строкового типа string, определяет поведение (перезаписать/не перезаписывать), если по такому пути существует локальный файл.

Возвращаемые значения

TRUE или FALSE, а также вызывает исключения по типовым событиям, например, AlreadyExistsException или NotFoundException.

示例

Скачать файл в локальную папку.

// без перезаписи
$resource->download(__DIR__.'/файл.txt');

// без перезаписи
$resource->download(__DIR__.'/файл.txt', false);

// с перезапсью
$resource->download(__DIR__.'/файл.txt', true);

Запись в открытый дескриптор.

// открыть любой дескриптор
$fp = fopen(__DIR__.'/файл.txt', 'wb+');

// или и т.д.
$fp = fopen('php://memory', 'r+b');

$resource->download($fp);

// продолжить работу ...
fseek($fp, 0);

Использовать обертку над потоком так же просто.

$stream = new Stream('php://temp', 'r+');

$resource->download($stream);

var_dump($stream->getSize());

1.3.8.12. Копирование файла или папки

Сделать копию ресурса.

public bool Closed::copy(mixed $destination [,bool  $overwrite = false])

$destination - путь до нового ресурса.

Может принимать значения

string - строка, путь от корня папки приложения или корня Яндекс.Диска.
Arhitector\Yandex\Disk\Resource\Closed - инициализированный объект другого ресурса.

$overwrite - признак перезаписи, если по указанному пути существует ресурс. Поведение по умолчанию FALSE.

Возвращаемые значения

TRUE или FALSE, а также Arhitector\Yandex\Disk\Operation в случае длительного копирования.

示例

// сделать копию файла
$resource->copy('папка/файл-копия.txt');

// сделать копию папки
$resource->copy('app:/папка-копия');

// сделать копию $resource по пути 'копия/путь до файла.txt'
$resource2 = $disk->getResource('копия/путь до файла.txt');
$resource->copy($resource2, true);

1.3.8.13. Загрузка файла

Метод upload безопасен от утечки памяти и используется для загрузки файлов на Яндекс.Диск. Может загружать как файлы расположенные локально, в локальной папке, так и, файлы расположенные на удаленном хостинге/сервере и доступные по URL-адресу.

public mixed upload(mixed $file_path [, bool $overwrite = false [, bool $disable_redirects = false]])

$file_path - может быть как путь к локальному файлу, так и URL к файлу.

Принимает значения

string - путь до локального файла или URL-адрес.
resource - дескриптор файла, открытый на чтение.

$overwrite - признак перезаписи, если ресурс на Яндекс.Диске существует. Параметр не влияет на загрузку файлов по URL-адресу.

$disable_redirects - 参数影响通过URL地址下载的文件。 TRUE 有助于禁止重定向到地址。默认行为 FALSE - 允许重定向。

示例

下载本地文件。

$resource->upload(__DIR__.'/файл.txt');

// загрузка с перезаписью
$resource->upload(__DIR__.'/файл.txt', true);

// если передан дескриптор файла, загрузка с перезаписью
$fp = fopen(__DIR__.'/файл.txt', 'rb');
$resource->upload($fp, true);

下载位于远程服务器上的文件。返回操作对象 Arhitector\Yandex\Disk\Operation。

$operation = $resource->upload('http://домен.ру/файл.zip');

// запретить пере адресацию.
$operation = $resource->upload('https://домен.ру/файл.zip', null, true);

1.3.8.14. 过滤方法

对象 Arhitector\Yandex\Disk\Resource\Closed 支持

setLimit
setOffset
setPreviewCrop
setPreview
setSort

1.3.9. 公共资源的工作

通过 Disk::getPublishResource 和 Disk::getPublishResources 方法处理具有开放访问权限的资源，这些方法由磁盘所有者访问。

方法 Disk::getPublishResource

获取特定资源在Yandex.Disk上的开放访问对象化表示。

public Resource\Closed Disk::getPublishResource(string $public_key [, int $limit = 20 [, int $offset = 0]])

$public_key - 公共密钥或开放访问资源的URL地址。

$limit - 如果是文件夹，则响应中的资源数量。

$offset - 偏移量。用于所有文件列表或如果资源是文件夹，则用于文件夹内资源的偏移量。

示例

获取资源对象。

/**
 * @var Arhitector\Yandex\Disk\Resource\Opened  $publicResource
 */
$publicResource = $disk->getResource('https://yadi.sk/d/g0N4hNtXcrq22');

$publicResource = $disk->getResource('wICbu9SPnY3uT4tFA6P99YXJwuAr2TU7oGYu1fTq68Y=', 10, 0);

可以在获取资源对象后通过方法 setLimit 和 setOffset 设置 $limit 和 $offset。

$publicResource->setLimit(100);

$publicResource->setOffset(200);

方法 Disk::getPublishResources，列出所有已发布的文件。

获取Yandex.Disk上所有开放访问文件列表以及等。列表以 Arhitector\Yandex\Disk\Resource\Collection 对象表示。

public Resource\Collection Disk::getPublishResources([, int $limit = 20 [, int $offset = 0]])

这里提供了过滤方法、基本获取信息方法和一系列其他方法。

示例

/**
 * Получить список всех файлов
 *
 * @var Disk\Resource\Collection  $collection
 */
$collection = $disk->getPublishResources();

$disk->getPublishResources(100, 15);

过滤方法

所有这些都在 API 端进行处理。对于集合，提供了以下方法

setLimit
setMediaType
setOffset
setPreviewCrop
setPreview
setSort

1.3.9.1. 获取公共密钥

获取用于获取资源访问权限的公共密钥或URL。

public string Opened::getPublicKey( void )

示例

$publicResource->getPublicKey();

1.3.9.2. 获取直接链接

获取文件的下载或文件夹的直接链接。

注意：返回的链接有效（“活着”）约两小时。

注意：此方法不支持获取公共文件夹内资源的链接。此功能可实现，但尚未实现。

public string Opened::getLink( void )

示例

$publicResource->getLink();

1.3.9.3. 下载公共文件或文件夹。

下载公共文件或文件夹（以zip存档形式）。

public bool Opened::download(mixed $destination [, bool $overwrite = false [, bool $check_hash = false]])

$destination - 文件将保存的路径

Принимает значения

string - 文件路径。
resource - 打开用于写入的文件描述符。
StreamInterface - 打开用于写入的流。

$overwrite - 如果 $destination 是文件路径，则重写标志。默认值为 FALSE。

$check_hash - 检查下载文件的完整性。值为 TRUE 允许检查下载文件的 md5 校验和。默认值为 FALSE。

示例

$publicResource->download(__DIR__.'/file.txt');

$publicResource->download(__DIR__.'/file.txt', true);

$publicResource->download(__DIR__.'/file.txt', true, true);

Запись в открытый дескриптор.

// открыть любой дескриптор
$fp = fopen(__DIR__.'/файл.txt', 'wb+');

// или и т.д.
$fp = fopen('php://memory', 'r+b');

// true - провести проверку целостности скачанного файла
$publicResource->download($fp, false, true);

// продолжить работу ...
fseek($fp, 0);

Использовать обертку над потоком так же просто.

$stream = new Stream('php://temp', 'r+');

$publicResource->download($stream);

var_dump($stream->getSize());

1.3.9.4. 是否可以代表所有者访问此文件。

/** * 该文件或相同文件位于我的磁盘上 * 此方法需要访问令牌 * * @return boolean */

 public function hasEqual()

1.3.9.5. 将公共文件保存到“下载”中。

/**
 * Сохранение публичного файла в «Загрузки» или отдельный файл из публичной папки
 *
 * @param    string $name Имя, под которым файл следует сохранить в папку «Загрузки»
 * @param    string $path Путь внутри публичной папки.
 *
 * @return    mixed
 */
 public function save($name = null, $path = null)

1.3.9.6. 设置公共文件夹内的路径。

/**
 * Устанавливает путь внутри публичной папки
 *
 * @param string $path
 *
 * @return $this
 */
 public function setPath($path)

1.3.10. 处理回收站文件。

/**
 * Ресурсы в корзине.
 *
 * @param    string $path путь к файлу в корзине
 * @param int       $limit
 * @param int       $offset
 *
 * @return \Arhitector\Yandex\Disk\Resource\Removed
 * @example
 *
 * $disk->getTrashResource('file.ext') -> toArray() // файл в корзине
 * $disk->getTrashResource('trash:/file.ext') -> delete()
 */
public function getTrashResource($path, $limit = 20, $offset = 0)

/**
 * Содержимое всей корзины.
 *
 * @param int $limit
 * @param int $offset
 *
 * @return \Arhitector\Yandex\Disk\Resource\Collection
 */
public function getTrashResources($limit = 20, $offset = 0)

1.3.10.1. 从回收站恢复资源。

/**
 *	Восстановление файла или папки из Корзины
 *	В корзине файлы с одинаковыми именами в действительности именют постфикс к имени в виде unixtime
 *
 *	@param	mixed	$name	оставляет имя как есть и если boolean это заменяет overwrite
 *	@param	boolean	$overwrite
 *	@return	mixed
 */
public function restore($name = null, $overwrite = false)

1.3.10.2. 从回收站删除资源。

/**
 * Удаление файла или папки
 *
 * @return    mixed
 */
public function delete()

1.3.11. 清空回收站。

/**
 * Очистить корзину.
 *
 * @return bool|\Arhitector\Yandex\Disk\Operation
 */
public function cleanTrash()

1.3.12. 最后下载的文件。

/**
 * Последние загруженные файлы
 *
 * @param    integer $limit
 * @param    integer $offset
 *
 * @return   \Arhitector\Yandex\Disk\Resource\Collection
 *
 * @example
 *
 * $disk->uploaded(limit, offset) // коллекия закрытых ресурсов
 */
public function uploaded($limit = 20, $offset = 0)

1.3.13. 同步操作。

/**
 * Получить статус операции.
 *
 * @param   string $identifier идентификатор операции или NULL
 *
 * @return  \Arhitector\Yandex\Disk\Operation
 *
 * @example
 *
 * $disk->getOperation('identifier operation')
 */
public function getOperation($identifier)

/**
 * Возвращает количество асинхронных операций экземпляра.
 *
 * @return int
 */
public function count()

	/**
 * Получить все операции, полученные во время выполнения сценария
 *
 * @return array
 *
 * @example
 *
 * $disk->getOperations()
 *
 * array (size=124)
 *  0 => 'identifier_1',
 *  1 => 'identifier_2',
 *  2 => 'identifier_3',
 */
public function getOperations()

1.3.14. 过滤方法。

/**
 * Количество ресурсов, вложенных в папку, описание которых следует вернуть в ответе
 *
 * @param    integer $limit
 * @param    integer $offset установить смещение
 *
 * @return   $this
 */
public function setLimit($limit, $offset = null)


/**
 * Количество вложенных ресурсов с начала списка, которые следует опустить в ответе
 *
 * @param    integer $offset
 *
 * @return    $this
 */
public function setOffset($offset)

	/**
 * Атрибут, по которому сортируется список ресурсов, вложенных в папку.
 *
 * @param    string  $sort
 * @param    boolean $inverse TRUE чтобы сортировать в обратном порядке
 *
 * @return    $this
 * @throws    \UnexpectedValueException
 */
public function setSort($sort, $inverse = false)

'Допустимые значения сортировки - name, path, created, modified, size'

	/**
 * Тип файлов, которые нужно включить в список
 *
 * @param    string $media_type
 *
 * @return    $this
 * @throws    \UnexpectedValueException
 */
public function setMediaType($media_type)
Тип файлов, которые нужно включить в список. Диск определяет тип каждого файла при загрузке.

要请求多个文件类型，可以在参数值的逗号分隔列表中列出它们。例如，media_type="audio,video"。支持类型：audio — 音频文件。backup — 备份和临时副本文件。book — 电子书。compressed — 压缩和存档文件。data — 数据库文件。development — 代码文件（C++、Java、XML等），以及IDE服务文件。diskimage — 不同格式的信息载体映像及其相关文件（例如，CUE）。document — 办公文档格式（Word、OpenOffice等）。encoded — 加密文件。executable — 可执行文件。flash — 含有闪存视频或动画的文件。font — 字体文件。image — 图片。settings — 各种程序的设置文件。spreadsheet — 办公表格文件（Numbers、Lotus）。text — 文本文件。unknown — 未知类型。video — 视频文件。web — 浏览器和网站使用的各种文件（CSS、证书、书签）。

	/**
 * Получает установленное значение.
 *
 * @return  string
 */
public function getMediaType()

	/**
 * Все возможные типы файлов
 *
 * @return array
 */
public function getMediaTypes()

	/**
 * Обрезать превью согласно размеру
 *
 * @param    boolean $crop
 *
 * @return    $this
 */
public function setPreviewCrop($crop)
Параметр позволяет обрезать превью согласно размеру, заданному в значении параметра preview_size.

允许的值: “false” — 参数被忽略。这是默认值。 “true” — 预览按以下方式裁剪：如果只传递宽度和/或高度，则图片按此大小缩小，同时保持比例。然后从缩小后的图像中心裁剪出指定边长的正方形。如果传递了精确尺寸（例如，“120x240”），则从原始图像中心裁剪出最大尺寸的指定宽度和高度的部分。然后裁剪的部分按指定尺寸缩放。

	/**
 * Размер уменьшенного превью файла
 *
 * @param    mixed $preview S, M, L, XL, XXL, XXXL, <ширина>, <ширина>x, x<высота>, <ширина>x<высота>
 *
 * @return    $this
 * @throws    \UnexpectedValueException
 */
public function setPreview($preview)
Вы можете задать как точный размер превью, так и размер одной из сторон. Получившееся изображение можно обрезать до квадрата с помощью параметра preview_crop.

值选项：预定义的最大边长尺寸。图片按最大边长缩小到指定尺寸，保持原始图片的比例。例如，对于尺寸“S”和120×200像素的图片，将生成90×150像素的预览，而对于300×100像素的图片，将生成150×50像素的预览。支持值：“S” — 150像素；“M” — 300像素；“L” — 500像素；“XL” — 800像素；“XXL” — 1024像素；“XXXL” — 1280像素。精确宽度（例如，“120”或“120x”）或精确高度（例如，“x145”）。图片按指定宽度和/或高度缩小，保持原始图片的比例。如果传递了preview_crop参数，则从缩小后的图像中心裁剪出指定边长的正方形。精确尺寸（格式为“<宽度>x<高度>”，例如“120x240”）。图片按指定尺寸缩小，保持原始图片的比例。如果传递了preview_crop参数，则从原始图像中心裁剪出最大尺寸的指定宽度和高度的部分（例如，1/2）。然后裁剪的部分按指定尺寸缩放。

	/**
 * Получает установленное значение "setPreview".
 *
 * @return  string
 */
public function getPreview()

	/**
 * Получает установленное значение "setPreviewCrop".
 *
 * @return  string
 */
public function getPreviewCrop()

	/**
 * Относительный путь к ресурсу внутри публичной папки.
 *
 * @param    string $path
 *
 * @return    $this
 */
public function setRelativePath($path)

	/**
 * Получает установленное значение.
 *
 * @return  string
 */
public function getRelativePath()

	/**
 * Тип ресурса
 *
 * @param    string $type
 *
 * @return    $this
 * @throws    \UnexpectedValueException
 */
public function setType($type)


	/**
 * Получает установленное значение.
 *
 * @return  string
 */
public function getType()

1.3.15 事件。

资源支持其事件。要获取更多信息，请阅读客户端事件描述（见下文）。可用事件列表

disk.downloaded - 事件在特定资源被下载时发生。
disk.uploaded - 事件在资源被上传时发生。
disk.operation - 当雅虎.磁盘对资源执行异步操作时（例如，移动大文件夹）发生。
disk.delete - 当特定资源被删除时发生，可以取消删除。

与客户端委托事件的区别在于这些事件的可见性。客户端为所有资源设置事件，尽管如此，每个资源都可以接收自己的事件。

事件可以接受多个处理程序。事件处理程序不会互相替换，而是按顺序添加到队列中。

示例

$resource->addListeners();

1.3.16 事件 `uploaded`

在执行本地文件上传请求后调用。

use Arhitector\Yandex\Disk;
use Arhitector\Yandex\Disk\Resource\Closed;
use League\Event\Event;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\StreamInterface;

// ... 
$disk->addListener('uploaded', function (Event $event, Closed $resource, Disk $disk, StreamInterface $uploadedStream, ResponseInterface $response) {
	// $event - событие
	// $resource - тоже самое что и $resource
	// $disk - клиент
	// $uploadedStream - в данном примере файл file_path.pdf обернутый в Stream
	// $response - Ответ от Я.Диска. $response->getBody() - не содержит ничего (см. документацию API Я.Диска)
});

// ...
$resource->upload(__DIR__.'/file_path.pdf');

编码标准

在修改代码时应遵守这些标准。标准基于PSR-2，并进行了一些修改。

管理结构

如if、for、foreach、while、switch等关键字应与参数/参数列表前的空格一起使用。括号应放在新的一行上，换行符应遵循相同的嵌套级别。

if ($arg === true)
{
    // некоторый код
}
elseif ($arg === null)
{
    // некоторый код
}
else
{
    // некоторый код
}

foreach ($array as $key => $value)
{
    // некоторый код
}

for ($i = 0; $i < $max; $i++)
{
    // некоторый код
}

while ($i < $max)
{
    // некоторый код
}

do
{
    // некоторый код
}
while ($i < $max)

switch ($var)
{
    case 'value1':
        // некоторый код
    break;

    default :
        // некоторый код
    break;
}

比较和逻辑运算符

运算符 ! 应在两侧有空格。

if ($var == false and $other_var != 'some_value')
if ($var === false or my_function() !== false)
if ( ! $var)

1. 与雅虎服务通信的基本客户端

基本客户端提供用于通过OAuth协议进行雅虎服务认证的功能。其他特定服务客户端继承自基本客户端（例如，Mackey\Yandex\Disk也继承了基本客户端的方法）。

public void Client::__construct([string $token = null])

$token - 可选参数，应用程序的OAuth令牌。

示例

$client = new Client();

$client = new Client('0c4181a7c2cf4521964a72ff57a34a07');

1.1. 数据交换格式

获取与雅虎服务通信的格式信息。

public string Client::getContentType( void )

示例

$client->getContentType(); // application/json

1.2. 设置应用程序ID

设置已注册应用程序的ID。

public this Client::setClientOauth(string $client_id)

$client_id - 字符串，应用程序ID

示例

$client->setClientOauth('123456789');

1.3. 获取应用程序ID

如果之前使用setClientOauth方法设置了ID，则返回应用程序ID。

public mixed Client::getClientOauth( void )

示例

$client->getClientOauth(); // null

$client->getClientOauth(); // string '123456789'

1.4. 设置应用程序密码

设置应用程序密码。应用程序密码在注册此应用程序时发放。

public this Client::setClientOauthSecret(string $client_secret)

示例

$client->setClientOauthSecret('--------');

1.5. 获取应用程序密码

返回之前设置的应用程序密码或NULL。

public mixed Client::getClientOauthSecret( void )

示例

$client->getClientOauthSecret(); // null

$client->getClientOauthSecret(); // string '--------'

1.6. 设置OAuth令牌

设置OAuth令牌以进行服务认证。不是所有服务都需要OAuth令牌。

public this Client::setAccessToken(string $token)

示例

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

1.7. 获取设置的OAuth令牌

获取之前设置的OAuth令牌或NULL。

public mixed Client::getAccessToken( void );

示例

$client->getAccessToken(); // null

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

1.8. 请求新的或更新已发放的OAuth令牌

允许获取OAuth令牌或更新之前发放的令牌。

public mixed refreshAccessToken(string $username, string $password [, bool $onlyToken = false])

成功时返回包含信息的对象，或者如果传递了参数$onlyToken = true，则只返回OAuth令牌。

$username - 注册应用程序的账户的用户名

$password - 账户密码

$onlyToken - 只返回字符串令牌

示例

$client->refreshAccessToken('username', 'password');

/* object(stdClass)[28]
  public 'token_type' => string 'bearer' (length=6)
	public 'access_token' => string 'c7621`6149032dwf9a6a7ca765eb39b8' (length=32)
	public 'expires_in' => int 31536000
	public 'uid' => int 241`68329
	public 'created_at' => int 1456882032 */

$client->refreshAccessToken('username', 'password', true);

/* string 'c7621`6b09032dwf9a6a7ca765eb39b8' (length=32) */

1.9. 设置事件处理器

SDK支持事件。每个服务都有自己的可能事件集。请访问http://event.thephpleague.com/2.0/以获取更多信息。

public this Client::addListener(string $event, mixed $listener [, int $priority = ListenerAcceptorInterface::P_NORMAL])

$event - 事件

$listener - ListenerInterface处理程序或callable

$priority - 优先级。 League\Event\EmitterInterface 预定义了3个优先级

EmitterInterface::P_HIGH: 100
EmitterInterface::P_NORMAL: 0
EmitterInterface::P_LOW: -100

示例

$client->addListener('disk.downloaded', function (Event $event, $resource) {
  // скачивание файла завершено
});

1.10. 删除事件处理器

删除之前设置的处理器。

public this Client::removeListener(string $event, mixed $listener)

$event - 事件

$listener - ListenerInterface处理程序或callable

示例

$client->removeListener('disk.downloaded', function (Event $event, $resource) {

});

1.11. 设置一次性处理器

设置处理器。

public this addOneTimeListener(string $event, mixed $listener [, int $priority = ListenerAcceptorInterface::P_NORMAL])

$event - 事件

$listener - ListenerInterface处理程序或callable

$priority - 优先级。 League\Event\EmitterInterface 预定义了3个优先级

EmitterInterface::P_HIGH: 100
EmitterInterface::P_NORMAL: 0
EmitterInterface::P_LOW: -100

示例

$client->addOneTimeListener('disk.downloaded', function (Event $event, $resource) {
  // скачивание файла завершено
});

1.12. 删除所有事件处理器

删除所有之前设置的处理程序。

public this removeAllListeners(string $event)

$event - 事件

示例

$client->removeAllListeners('disk.downloaded');

1.13. 基于类的イベントハンドラ

基于类添加监听器。

public this useListenerProvider(ListenerProviderInterface $provider)

$provider - 类对象

示例

$client->useListenerProvider(new MyProvider);

1.14. 触发事件

执行事件监听器的调用。

public mixed emit(string $event)

$event - 事件

示例

$client->emit('custom.event', 'custom parameter', 'etc.');

ufee / yandex-disk

维护者

详细信息

README

变更记录

要求

为发展做出贡献

安装

测试

1. Yandex.Disk服务

1.1. 简介

1.1.1. 功能

插件、扩展、适配器

1.1.2. 应用程序文件夹

1.1.3. 使用示例

1.2 如何连接到Яндекс.Диск

1.2.1 设置OAuth令牌

1.2.2 获取设置的OAuth令牌

1.3 与Яндекс.Диск交互

介绍

1.3.1 get方法

1.3.2 toArray方法

1.3.3 toObject方法

1.3.4 getIterator方法

1.3.5 count方法

1.3.6 has和hasProperty方法

has方法

hasProperty方法

1.3.7. 获取磁盘信息。

1.3.8. 处理受限资源。

方法 Disk::getResource

方法 Disk::getResources，所有文件的列表。

方法 getFirst

方法 getLast

过滤方法

1.3.8.1. 检查资源是否存在

1.3.8.2. 获取资源信息

1.3.8.3. 资源是文件/文件夹

1.3.8.4. 资源是公开的/或仅对所有者可用

1.3.8.5. 磁盘上资源的路径

1.3.8.6. 为资源添加/删除元信息

删除信息

方法 getProperty

Метод getProperties

1.3.8.7. Удаление файла или папки

1.3.8.8. Перемещение файла или папки

1.3.8.9. Создание папки

1.3.8.10. Публикация ресурса\Закрытие доступа

1.3.8.11. Скачивание файла

1.3.8.12. Копирование файла или папки

1.3.8.13. Загрузка файла

1.3.8.14. 过滤方法

1.3.9. 公共资源的工作

方法 Disk::getPublishResource

方法 Disk::getPublishResources，列出所有已发布的文件。

过滤方法

1.3.9.1. 获取公共密钥

1.3.9.2. 获取直接链接

1.3.9.3. 下载公共文件或文件夹。

1.3.9.4. 是否可以代表所有者访问此文件。

1.3.9.5. 将公共文件保存到“下载”中。

1.3.9.6. 设置公共文件夹内的路径。

1.3.10. 处理回收站文件。

1.3.10.1. 从回收站恢复资源。

1.3.10.2. 从回收站删除资源。

1.3.11. 清空回收站。

1.3.12. 最后下载的文件。

1.3.13. 同步操作。

1.3.14. 过滤方法。

1.3.15 事件。

1.3.16 事件 uploaded

编码标准

管理结构

比较和逻辑运算符

1. 与雅虎服务通信的基本客户端

1.1. 数据交换格式

1.2. 设置应用程序ID

1.3. 获取应用程序ID

1.4. 设置应用程序密码

1.5. 获取应用程序密码

1.3.16 事件 `uploaded`