README

这是 Petitions.io API 的 PHP 封装

内容

安装
先决条件
使用方法

安装

使用 composer 进行安装。运行以下命令将此包包含到您的项目中
composer require cloudwelder/petitions-api

先决条件

为了使用此包，您必须在 petitions.io 上有一个活动的应用。如果您还没有，请在 petitions.io 上注册一个。注册后，记下您的 client_id、client_secret 和 redirect_uri，或者您可以直接获取一个 personal access token。

使用方法

在使用任何 API 类之前，确保您的代码中包含以下行。如果您使用的是类似 laravel 这样的框架，则此行不是必需的。

require "vendor/autoload.php"

初始化 API。

要使用任何 API 调用，您必须首先获取 API 实例并使用以下任何一种方法获取访问令牌。

方法 1：使用 API 凭证。

use CloudWelder/PetitionsApi/PetitionsApi;

$api = new PetitionsApi('client_id', 'client_secret', 'reidrect_uri');

将 client_id、client_secret、redirect_uri 替换为您自己的值。

生成登录 URL

要从用户那里获取访问权限，您必须首先将其重定向到 petitions.io。您可以使用 getRedirectUrl() 方法生成此 URL。

$redirectUrl = $api->generateRedirectUrl();

然后，您可以使用此 URL 来重定向用户或将其作为 HTML 链接的 href。

echo "<a href='$redirectUrl'>Click here to login</a>";

获取访问令牌

一旦用户已授予您的应用访问请求，petitions.io 将用户重定向到您在 petitions.io 中的 redirect_uri 设置中指定的 URL。这是您应该使用作为 URL 的一部分传输的授权代码来获取访问令牌的地方。

$token = $api->generateTokenFromCode($_GET['code']);
$accessToken = $token->getAccessToken();

将此 access_token 存储到数据库或其他持久化存储中，以便以后使用。除非用户撤销授权，否则此访问令牌有效很长时间（一年）。

返回的 Token 对象还将包含一个 refresh_token，除了 access_token 之外。您可以使用 getRfreshToken() 函数检索它。刷新令牌可以用来在它们过期时重新生成访问令牌。

方法 2：使用个人访问令牌。

如果您已经有一个活动的个人访问令牌，则无需任何凭证即可初始化 API

use CloudWelder/PetitionsApi/PetitionsApi;

$api = new PetitionsApi();

调用 API

API 对象提供了四种方法来调用 API。它们都返回一个 CloudWelder/PetitionsApi/Response 实例。返回的对象包含与 HTTP 响应相关的信息，例如头部、状态码和响应内容。Petitions.io 总是以 JSON 格式返回响应。因此，您必须解析响应体才能实际使用数据。然而，响应对象有一个辅助方法 getResponseData()，它将返回由解析响应内容生成的关联数组。

在调用任何 API 调用之前，请记得使用 withToken() 方法设置访问令牌。此方法是可链的，因此您可以将其他方法链接到它。

四个 API 调用方法如下

get() 用于向 API 端点发出 GET 请求。 签名：get($url, $data)
- $url API 端点
- $data 一个关联数组，包含要随调用一起传递的任何数据。例如

//Get the details of the active user.
$response = $api->withToken($accessToken)->get('users/me');
$userDetails = $response->getResponseData();

post() 用于向 API 端点发出 POST 请求。
签名：post($url, $data)
- $url API 端点
- $data 一个关联数组，包含要随调用一起传递的任何数据。例如

//Create a new petition.
$petitionData = [
  'title' =>  'My petition',
  'description' => 'This is a sample petition'
];
$response = $api->withToken($accessToken)->post('petitions', $petitionData);
$createdPetition = $response->getResponseData();

put() 用于向 API 端点发出 PUT 请求。
签名：put($url, $data)
- $url API 端点
- $data 一个关联数组，包含要随调用一起传递的任何数据。例如

//Edit an existing petition
$petitionData = [
  'title' =>  'My new petition'
];
$response = $api->withToken($accessToken)->put('petitions/2', $petitionData);
$changedPetition = $response->getResponseData();

delete() 用于向API端点发送DELETE请求。
签名：put($url)
- $url API端点示例

//Delete a petition
$response = $api->withToken($accessToken)->delete('petitions/2', $petitionData);

cloudwelder / petitions-api

维护者

详细信息