README

非官方的雅虎某些服务的PHP SDK：雅虎磁盘。

变更日志

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. 雅虎磁盘服务

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:/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-токен');

初始化Yandex Диск客户端并传递 $client。

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

选项2. 通过构造函数传递OAuth令牌来初始化Yandex Диск客户端。

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

选项3. 不传递OAuth令牌来初始化Yandex Диск客户端。

您可以在已初始化的对象中设置或更改OAuth令牌。

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

或更改Yandex Диск客户端的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. 与Yandex Диск交互

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方法的行为不同。它可以检查属性是否存在或资源在Yandex Диск上是否存在。

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

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一起使用，确定行为（覆盖/不覆盖），如果存在具有该路径的本地文件。

返回值

可以是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 — 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' 和 120x200 像素的图片，将生成 90x150 像素的预览，而对于 300x100 像素的图片，将生成 150x50 像素的预览。支持的值包括：'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 - 当 Yandex.Disk 对资源执行异步操作时（例如，移动大文件夹）触发此事件。
disk.delete - 当删除特定资源时触发此事件，可以取消删除。

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

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

示例

$resource->addListeners();

编码标准

修改代码时必须遵守这些标准。该标准基于 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. 与 Yandex 服务通信的基本客户端

基本客户端提供用于在采用 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'

请求新令牌或更新已发放的令牌

允许获取 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 处理器或可调用

$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 处理器或可调用

示例

$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 处理器或可调用

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

diat / yandex

维护者

详细信息

README

变更日志

要求

为发展做出贡献

安装

测试

1. 雅虎磁盘服务

1.1. 简介

1.1.1. 功能

插件、扩展、适配器

1.1.2. 应用程序文件夹

1.1.3. 使用示例

1.2. 如何连接到雅虎磁盘

1.2.1. 设置OAuth令牌

1.2.2. 获取设置的OAuth令牌

1.3. 与Yandex Диск交互

介绍

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. 与 Yandex 服务通信的基本客户端

1.1. 数据交换格式

1.2. 设置应用程序 ID

1.3. 获取应用程序 ID

1.4. 设置应用程序密码

1.5. 获取应用程序密码

1.6. 设置 OAuth 令牌