README

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

变更日志

5/7/2022

更新了依赖项并修正了代码

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 >= 7.3
php_curl 扩展

为发展做出贡献

您可以报告 SDK 工作中的不准确之处，欢迎在开发中提供帮助。要开始帮助开发，您需要创建 development 分支的 fork，修改代码，然后将更改以 pull request 的形式发送给我们到 development 分支。

安装

支持使用包管理器安装。

$ composer require s00d/yandex dev-master

或者

$ php composer.phar require s00d/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/MyFirstApplication/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 方法

获取雅虎云盘上特定资源的面向对象表示。磁盘所有者有权访问此类资源。

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', []);

资源是文件/文件夹

存在 isFile 和 isDir 方法来处理。

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

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

示例

$resource->isFile(); // true

$resource->isDir(); // false

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

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

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

示例

$resource->isPublish(); // false

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

磁盘上的资源路径

可以使用 getPath 方法来实现。此路径由 SDK 使用，尽管值可能与 Yandex Диск 返回的值不同，但这种不匹配是完全正确的。

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 - 当 $meta 为字符串时，使用 NULL 来删除特定的元信息。

示例

$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 - 对象同步操作，如果 Yandex Диск 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 Диск 根目录开始的路径。
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` 方法

获取雅虎云盘上公开访问资源的面向对象表示。

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` 方法，列出所有已发布的文件。

获取雅虎云盘上所有公开访问文件列表等。列表以对象 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”和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();

编码标准

在修改代码时应遵守这些标准。该标准基于 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协议的Yandex服务上完成认证的功能。其他特定服务的客户端（例如，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令牌或更新之前发放的令牌。

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

在成功的情况下返回包含信息的对象或仅返回OAuth令牌（如果传递了参数$onlyToken = true）。

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

速鸟 / 雅虎

维护者

详细信息

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. 与雅虎磁盘交互

介绍

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

1.1 数据交换格式

1.2 设置应用程序ID

1.3 获取应用程序ID

1.4 设置应用程序密码

1.5 获取应用程序密码

1.6 设置OAuth令牌

`Disk::getPublishResource` 方法

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