README

PHP 的 OneDrive SDK 是一个开源库，允许 PHP 应用程序以编程方式与 OneDrive REST API 交互。

它支持创建、读取、更新、删除（CRUD）文件和文件夹等操作，以及将它们移动或复制到其他文件夹。

要求

使用 PHP 的 OneDrive SDK 需要

PHP 7.3 或更高版本;
Composer 或手动安装 composer.json 中提到的依赖项。

测试

运行其功能测试还需要

一个配置了 https://:7777/ 作为其重定向 URI 的 OneDrive 网络应用程序；
一个 WebDriver 服务器，例如 Selenium 的 Java 独立服务器；
Chrome 浏览器 & ChromeDriver，并且它们必须能够由 WebDriver 服务器使用。

安装

推荐使用 Composer 安装 OneDrive SDK for PHP。

composer require krizalys/onedrive-php-sdk

如果您还没有在 PHP 项目中使用 Composer，请参阅 Composer 文档了解如何设置它。

快速开始

要使用 PHP 的 OneDrive SDK，您需要一个暴露 URL 初始化授权流程的 Web 应用程序。通常，该 URL，称为您的 Web 应用程序的 重定向 URI，是一个请求授权令牌的 PHP 脚本。此令牌在您的 Web 应用程序与用户 OneDrive 内容交互时是必需的，并且可以在多个调用之间重用。此类 Web 应用程序的示例是我们的功能测试套件。

您还需要一个 OneDrive 应用程序。要注册此类应用程序，首先登录到 Microsoft Azure，然后访问应用程序注册并为您应用程序添加一个注册。在注册您的应用程序时，您需要设置其 重定向 URI，如上所述。我们目前仅支持 Web 重定向 URI。

创建后，您的应用程序将分配一个 应用程序（客户端）ID，称为其 客户端 ID。在 证书 & 密钥 中，您还需要添加至少一个 客户端密钥。 警告：客户端密钥 与密码或私钥类似，允许应用程序代表您进行身份验证：因此，客户端密钥 应该保密。

一旦您有了 重定向 URI、客户端 ID 和 客户端密钥，您的 Web 应用程序就可以通过以下三个步骤开始使用 PHP 的 OneDrive SDK。

步骤 1：创建您的配置

由于您可能需要它们来执行多个脚本，我们建议将您的 客户端 ID、客户端密钥 和 重定向 URI 保存到配置文件中，例如

`config.php`

<?php

return [
    /**
     * Your OneDrive client ID.
     */
    'ONEDRIVE_CLIENT_ID' => '<YOUR_CLIENT_ID>',

    /**
     * Your OneDrive client secret.
     */
    'ONEDRIVE_CLIENT_SECRET' => '<YOUR_CLIENT_SECRET>',

    /**
     * Your OneDrive redirect URI.
     */
    'ONEDRIVE_REDIRECT_URI' => 'http://your.domain.com/redirect.php',
];

步骤 2：将用户引导到登录页面

此脚本负责，给定一组权限，从 OneDrive API 获取登录 URL。它需要将用户引导到该 URL 以启动他们的登录和权限授予过程。脚本应如下所示

`index.php`

<?php

($config = include __DIR__ . '/config.php') or die('Configuration file not found');
require_once __DIR__ . '/vendor/autoload.php';

use Krizalys\Onedrive\Onedrive;

// Instantiates a OneDrive client bound to your OneDrive application.
$client = Onedrive::client($config['ONEDRIVE_CLIENT_ID']);

// Gets a log in URL with sufficient privileges from the OneDrive API.
$url = $client->getLogInUrl([
    'files.read',
    'files.read.all',
    'files.readwrite',
    'files.readwrite.all',
    'offline_access',
], $config['ONEDRIVE_REDIRECT_URI']);

session_start();

// Persist the OneDrive client' state for next API requests.
$_SESSION['onedrive.client.state'] = $client->getState();

// Redirect the user to the log in URL.
header('HTTP/1.1 302 Found', true, 302);
header("Location: $url");

步骤 3：获取 OAuth 访问令牌

用户跟随此 URL 后，需要登录到他们的 Microsoft 账户，并询问他们是否同意允许您的 Web 应用程序访问他们的 OneDrive 账户。

如果他们同意，他们将重定向到您的 重定向 URI，并且 URL 的查询字符串中会传递一个 code。此 URL 上的脚本基本上

从您的配置和之前实例的状态中实例化一个 Client；
使用 Client::obtainAccessToken() 获取 OAuth 访问令牌，并将其接收到的 code 传递给它；
开始与存储在他们的 OneDrive 账户中的文件和文件夹进行交互，或将此责任委托给其他脚本，这些脚本反过来可能从相同的状态生成其他 Client 实例。

通常如下所示（将 /path/to 替换为适当的值）

`redirect.php`

<?php

($config = include __DIR__ . '/config.php') or die('Configuration file not found');
require_once __DIR__ . '/vendor/autoload.php';

use Krizalys\Onedrive\Onedrive;

// If we don't have a code in the query string (meaning that the user did not
// log in successfully or did not grant privileges requested), we cannot proceed
// in obtaining an access token.
if (!array_key_exists('code', $_GET)) {
    throw new \Exception('code undefined in $_GET');
}

session_start();

// Attempt to load the OneDrive client' state persisted from the previous
// request.
if (!array_key_exists('onedrive.client.state', $_SESSION)) {
    throw new \Exception('onedrive.client.state undefined in $_SESSION');
}

$client = Onedrive::client(
    $config['ONEDRIVE_CLIENT_ID'],
    [
        // Restore the previous state while instantiating this client to proceed
        // in obtaining an access token.
        'state' => $_SESSION['onedrive.client.state'],
    ]
);

// Obtain the token using the code received by the OneDrive API.
$client->obtainAccessToken($config['ONEDRIVE_CLIENT_SECRET'], $_GET['code']);

// Persist the OneDrive client' state for next API requests.
$_SESSION['onedrive.client.state'] = $client->getState();

// Past this point, you can start using file/folder functions from the SDK, eg:
$file = $client->getRoot()->upload('hello.txt', 'Hello World!');
echo $file->download();
// => Hello World!

$file->delete();

有关可用类和方法的详细信息，请参阅 API 参考或项目页面（在 Krizalys）。

版本控制

PHP 的 OneDrive SDK 遵循语义版本控制：我们承诺不会在不增加主版本号的情况下引入破坏性更改到公共 API。我们还在变更日志中记录此类更改。

然而，我们只考虑带有 @api 注解的符号是公共 API 的一部分，并受语义版本控制要求。**其他符号被认为是内部符号，可能会更改或删除，而无需增加主版本号**。为了避免破坏性更改，请在您的代码中仅使用公共 API 中的符号。

测试

运行功能测试套件

在 test/functional/config.php 中设置您的应用程序配置；

运行 WebDriver 服务器，例如

java -jar selenium-server-standalone-3.141.59.jar

运行功能测试套件（它假定 WebDriver 在 4444 端口上监听）

vendor/bin/paratest --functional --configuration test --testsuite 'Functional tests' --bootstrap test/functional/bootstrap.php

根据需要重复步骤 3。

许可

PHP 的 OneDrive SDK 是在 3 条款 BSD 许可证下许可的。

致谢

PHP 的 OneDrive SDK 由 Christophe Vidal 开发和维护。

alfredo579 / onedrive-php-sdk

维护者

详情