README

PHP SDK 文档： https://developers.dailymotion.com/sdk/platform-sdk/php/

此仓库包含官方开源 PHP SDK，该 SDK 可简化 PHP 应用程序访问 Dailymotion 平台 API。有关使用 Dailymotion 服务进行开发的更多信息，请访问 开发者门户。

使用方法

PHP SDK 实现了 Dailymotion 平台 API。有关所有可用对象、字段和筛选器的列表，请参阅完整的 API 参考。要使用 PHP SDK 调用方法，请使用 get、post 或 delete 方法，如下所示

$api = new Dailymotion();
$result = $api->get(
    '/videos',
    array('fields' => array('id', 'title', 'owner'))
);

$result 变量包含方法的返回结果（如 平台 API 基础 中所述），以 数组 的形式。

身份验证

平台 API 需要OAuth 2.0身份验证才能访问受保护资源。

与大多数OAuth SDK不同，Dailymotion PHP SDK 实现了 延迟身份验证，这意味着只要不请求API中的数据，就不会发送身份验证请求。在此之后，在第一次请求信息时，会连续发送两个请求，一个用于身份验证，一个用于获取数据。在阅读其余文档时请记住这一点。

请注意，Dailymotion PHP SDK 还负责抽象整个 OAuth 流，从检索、存储和使用访问令牌，到使用刷新令牌自动获取新的访问令牌。您无需手动处理访问令牌，但如果必须这样做，在编程级别上，SDK通过 Dailymotion::getSession() 和 Dailymotion::setSession() 方法公开此信息。在OAuth级别上，一个 会话 是OAuth服务器在成功认证后发送的响应，例如

{
    "access_token": "<ACCESS_TOKEN>",
    "token_type": "Bearer",
    "expires_in": 36000,
    "refresh_token": "<REFRESH_TOKEN>",
    "scope": "<SCOPE1 SCOPE2 SCOPE3>",
    "uid": "<USER_ID>"
}

注意：OAuth 2.0的一个问题是，规范没有提供任何机制来升级现有会话的范围。要向现有会话添加新的作用域，您首先需要调用 Dailymotion::logout() 方法，然后使用您的新作用域列表启动一个新的会话。

如果您真的希望手动检索访问令牌，而无需等待 SDK 在发送第一次查询时处理它，您可以使用 Dailymotion::getAccessToken() 方法。它将尝试进行身份验证并返回相应的访问令牌或异常。请注意，这不是推荐的做法。有关处理访问令牌的更多信息，请参阅过度使用 SDK 部分。

此库实现了三种 OAuth 2.0 授权方法，用于不同的使用情况。

授权授予类型

这种授权类型是在大多数情况下你应该使用的类型。使用这种授权类型，你将用户重定向到Dailymotion的授权页面，一旦最终用户授权你的API密钥代表他们访问Dailymotion，你的应用程序就会被回调。

下面是一个使用示例

// Instanciate the PHP SDK.
$api = new Dailymotion();

// Tell the SDK what kind of authentication you'd like to use.
// Because the SDK works with lazy authentication, no request is performed at this point.
$api->setGrantType(Dailymotion::GRANT_TYPE_AUTHORIZATION, $apiKey, $apiSecret);

try
{
    // The following line will actually try to authenticate before making the API call.
    // * The SDK takes care of retrying if the access token has expired.
    // * The SDK takes care of storing the access token itself using its `readSession()`
    //   and `storeSession()` methods that are made to be overridden in an extension
    //   of the class if you want a different storage than provided by default.
    $result = $api->get(
        '/me/videos',
        array('fields' => array('id', 'title', 'owner'))
    );
}
catch (DailymotionAuthRequiredException $e)
{
    // If the SDK doesn't have any access token stored in memory, it tries to
    // redirect the user to the Dailymotion authorization page for authentication.
    return header('Location: ' . $api->getAuthorizationUrl());
}
catch (DailymotionAuthRefusedException $e)
{
    // Handle the situation when the user refused to authorize and came back here.
    // <YOUR CODE>
}

密码授权类型

如果你的PHP应用程序不是Web应用程序，不能将用户重定向到Dailymotion的授权页面，则可以使用密码授权类型来代替授权类型。使用这种授权类型，你需要负责要求用户提供其凭证。不过，请确保你的API密钥仍然是保密的，如果你不希望你的API密钥公开曝光，请不要将这种认证用于任何在客户端运行的服务。

下面是一个使用示例

// Instanciate the PHP SDK.
$api = new Dailymotion();

// Ask the end-user for his/her Dailymotion credentials in a way or another.
if (empty($_POST['username']) || empty($_POST['password']))
{
    // <YOUR CODE>
}
else
{
    // Tell the SDK what kind of authentication you'd like to use. Because the SDK
    // works with lazy authentication, no request is performed at this point.
    $api->setGrantType(
        Dailymotion::GRANT_TYPE_PASSWORD, 
        $apiKey,
        $apiSecret,
        array(), // OAuth 2.0 scopes that you'd like to be granted by the end-user
        array(
            'username' => $_POST['username'], // don't forget to sanitize this,
            'password' => $_POST['password'], // never use POST variables this way
        )
    );
    // The following line will actually try to authenticate before making the API call.
    // * The SDK takes care of retrying if the access token has expired.
    // * The SDK takes care of storing the access token itself using its `readSession()`
    //   and `storeSession()` methods that are made to be overridden in an extension
    //   of the class if you want a different storage than provided by default.
    $result = $api->get(
        '/me/videos',
        array('fields' => array('id', 'title', 'owner'))
    );
}

客户端凭证授权类型

如果你不需要代表他人访问Dailymotion API，例如，你只计划访问公开数据，你可以使用客户端凭证授权类型。使用这种授权类型，你只能访问公开数据或受特定作用域和/或角色保护的数据。这相当于未登录但被授权（由Dailymotion作为合作伙伴计划或类似计划的一部分）访问敏感数据。

下面是一个使用示例

// Instanciate the PHP SDK.
$api = new Dailymotion();

// Tell the SDK what kind of authentication you'd like to use. 
// Because the SDK works with lazy authentication, no request is performed at this point.
$api->setGrantType(Dailymotion::GRANT_TYPE_CLIENT_CREDENTIALS, $apiKey, $apiSecret);

// This will actually try to authenticate before making the API call.
// * The SDK takes care of retrying if the access token has expired.
// * The SDK takes care of storing the access token itself using its `readSession()`
//   and `storeSession()` methods that are made to be overridden in an extension
//   of the class if you want a different storage than provided by default.
$result = $api->get(
    '/videos',
    array('fields' => array('id', 'title', 'owner'))
);

在此场景中没有任何认证用户，因此你将无法访问/me端点。

上传文件

某些方法，如POST /me/videos，需要文件的URL。为了创建这些URL，Dailymotion通过Dailymotion::uploadFile()方法提供临时上传服务，可以使用如下方式

// Temporarily upload a file on Dailymotion' servers
// This does not create a video, it only offers you a public URL to work with.
$url = $api->uploadFile('/Path/to/your/local/video/file');
var_dump($url);

然后你可以使用这个$url结果作为需要此类参数的方法的参数。例如，创建一个视频

// More fields may be mandatory in order to create a video.
// Please refer to the complete API reference for a list of all the required data.
$result = $api->post(
    '/me/videos',
    array('url' => $url, 'title' => $videoTitle)
);

你还可以这样检索进度URL

$progressUrl = null;
$url = $api->uploadFile($filePath, null, $progressUrl);
var_dump($progressUrl);

上传开始后访问此URL允许你监控上传进度。

重载SDK

如上文中认证部分所述，PHP SDK负责抽象整个OAuth流程，从检索、存储和使用访问令牌，到使用刷新令牌自动收集新的访问令牌。

通过你的实现重载SDK允许你根据需要调整SDK的行为。最常见的使用方法是将Dailymotion::storeSession()和Dailymotion::readSession()方法重载，以更改默认存储系统（使用cookie）。

以下是一个示例，展示了如何重载SDK以将会话（访问令牌+刷新令牌）存储在文件系统上，而不是使用cookie（例如，用于命令行程序）

class DailymotionCli extends Dailymotion
{
    /**
     * Where to store the current application session.
     * @var string
     */
    protected static $sessionFile;

    /**
     * Define where to store the session on the file system.
     */
    public function __construct()
    {
        self::$sessionFile = __DIR__ . '/api-session.json';
    }
    /**
     * Overloading the default implementation with file system implementation.
     * `readSession` is used to restore the session from its storage medium.
     * @return array Restored session information.
     */
    protected function readSession()
    {
        $session = json_decode(file_get_contents(self::$sessionFile), true);
        return $session;
    }
    /**
     * Overloading the default implementation with file system implementation.
     * `storeSession` is used to store the session to its storage medium.
     *
     * @param array $session Session information to store.
     * @return DailymotionCli $this
     */
    protected function storeSession(array $session = array())
    {
        file_put_contents(self::$sessionFile, json_encode($session), LOCK_EX);
        return $this;
    }
}

不要犹豫，扩展SDK的功能，完成后向我们发送pull requests！再次提醒，如果你认为有什么问题，不要犹豫，向我们报告任何问题。