README

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

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

要求

使用 PHP 的 OneDrive SDK 需要以下内容

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

测试

运行其功能测试还需要以下内容

配置了 https://:7777/ 作为其重定向 URI 的 OneDrive 网络应用程序；
WebDriver 服务器，例如 Selenium Server (Grid)；
Chrome 浏览器和 ChromeDriver，并且它们必须可通过 WebDriver 服务器使用。

安装

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

composer require krizalys/onedrive-php-sdk

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

快速入门

要使用 PHP 的 OneDrive SDK，您需要一个公开 URL 的网络应用程序，用于启动授权流程。通常，此 URL，称为您的网络应用程序的 重定向 URI，是一个请求授权令牌的 PHP 脚本。此令牌在您的网络应用程序与您的用户的 OneDrive 内容交互时需要，并且可以在多个调用中重复使用。此类网络应用程序的示例是我们的功能测试套件。

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

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

一旦您有了 重定向 URI、客户端 ID 和 客户端密钥，您的网络应用程序就可以通过以下三个步骤开始使用 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-4.8.3.jar standalone

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

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

如有需要，重复步骤 3。

许可协议

PHP 的 OneDrive SDK 采用3-Clause BSD 许可协议。

鸣谢

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

krizalys / onedrive-php-sdk

维护者

详细信息