README

非官方PHP SDK，用于一些雅虎服务：雅虎. Disk。

变更日志

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 分支的 fork，修改代码，然后将更改作为 pull request 发送给我们，以提交到 development 分支。

安装

支持使用包管理器安装。

$ composer require arhitector/yandex dev-master

或者

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

测试

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

$ composer test

1. 雅虎. Disk 服务

1.1. 简介

用于与雅虎. Disk 交互的PHP SDK，其基础是磁盘 REST API。磁盘 API 使用 OAuth-令牌（例如，0c4181a7c2cf4521964a72ff57a34a07）进行身份验证，您需要自己获取

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

SDK 仅与调试令牌一起工作。OAuth-令牌必须具有“雅虎. Disk REST API”的授权权限。

资源 - 雅虎. Disk 上的文件或文件夹。SDK 定义三种资源状态：公开、私有和被放入 回收站 的。

1.1.1. 功能

主要功能

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

可能不是完整的列表

插件、扩展、适配器

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

1.1.2. 应用程序文件夹

应用程序可以在用户的磁盘上存储自己的数据 - 例如，用户设置的配置或由用户创建的文件。要请求访问磁盘上的自己的文件夹，应用程序需要注册具有“访问磁盘上的应用程序文件夹”权限。这样的应用程序只能在其文件夹内操作文件，除非它还获得了访问磁盘的权限。SDK 区分公共访问和应用程序对自身文件夹的访问，分别使用“disk:”和“app:”前缀。不过，在资源信息中，路径以 disk:/ 方案表示，使用资源的绝对路径，例如“disk:/Applications/我的第一应用/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等）

示例

// индекс 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

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

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 使用，尽管值可能与 Yandex.Disk 返回的值不同，但这种不匹配是完全正确的。

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 字符串类型一起使用，定义行为（覆盖/不覆盖），如果本地文件存在。

返回值

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 - 字符串，从应用程序文件夹根目录或Yandex.Disk根目录开始的路径。
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 不会导致内存泄漏，并用于将文件上传到Yandex.Disk。可以上传位于本地、本地文件夹中，以及位于远程主机/服务器上且可通过URL访问的文件。

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

$file_path - 可以是本地文件的路径，也可以是文件的URL。

接受值

string - 本地文件路径或URL地址。
resource - 打开的文件读取描述符。

$overwrite - 如果Yandex.Disk上的资源存在，则表示覆盖标志。此参数不影响通过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。

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.');

架构师 / yandex

维护者

详情

README

变更日志

要求

贡献代码

安装

测试

1. 雅虎. 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. 获取应用程序密码

`Disk::getPublishResource` 方法

`Disk::getPublishResources` 方法，列出所有公开文件。

1.3.16 事件 `uploaded`