README

此仓库包含官方开源PHP SDK，可简化PHP应用程序访问 Dailymotion Graph 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 变量包含方法的结果（如 Graph API概述 中所述），作为 array。

身份验证

Dailymotion 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！再次提醒，如果您认为有错误，不要犹豫，随时报告任何问题。