README

通过OAuth与Patreon API交互。

关于从早期版本更新到1.0.0的重要说明

Patreon PHP库版本1.0.0迁移到Patreon的v2 API，它与旧版v1调用不兼容。它还移除了Art4 JSON库。因此，直接从旧版本升级到1.0.0会破坏您安装的兼容性。APIv1将在APIv2推出beta版后不久弃用，因此使您的集成与API v2兼容非常重要。使用API v2，您只能访问在授权期间请求的作用域，您需要通过includes请求所需的数据。

如果您之前使用Art4库，您可以单独安装它，并在从该库获取JSON格式数据后将其返回值传递给Art4库，这将使使用Art4库的现有代码兼容。然而请注意，您需要自行跟踪Art4库的更新和由此产生的兼容性问题。

https://docs.patreon.com/#apiv2-oauth

如果您有任何问题或问题，请访问我们的开发者论坛https://www.patreondevelopers.com/

注意：此库旨在与尽可能多的不同基础设施、PHP版本和环境兼容，以涵盖大多数潜在的集成。如果您想使用更专业的库版本，具有不同的便利设施和添加/依赖项以更好地适应您的环境，以下是一份列表。如果您想将您的分支添加到这份列表中，请通过论坛联系我们。

soatok的分支，使用PHP 7.x、PHPunit、Psalm、BLAKE2b替代MD5

安装

目前packagist上的repo处于0.3.x和API v1版本，而Github上的repo处于1.0.0和API v2版本，这是由于旧版安装的兼容性原因，这些安装是通过composer完成的。在我们将packagist版本与Github版本同步之前，请通过从Github克隆它或通过文件传输下载并上传到您的环境来使用此repo。

使用方法

步骤1. 获取您的client_id和client_secret

以Patreon创建者的身份登录，访问Patreon平台文档页面以注册您的客户端。

这将为您提供client_id和client_secret。

步骤2. 在您的代码中使用此插件

假设您想创建一个“使用Patreon登录”按钮。

您已经阅读了说明，并正在尝试与您的服务器一起实现“步骤2：处理OAuth重定向”。

用户将在您将他们发送到[授权页面]（www.patreon.com/oauth2/authorize）进行步骤1之后到达您的页面之一，因此在他们查询参数中到达此页面的情况下，他们会有一个参数'code'。

（如果您执行的不是“使用Patreon登录”流程，请参阅示例文件夹以获取更多示例）

（特别是统一流程是让用户在您的网站或应用中解锁锁定功能或内容的好方法 - 它允许用户注册、登录、承诺并在一个流畅的统一流程中返回您的应用。在示例文件夹中查看）

<?php

// This example shows how to have your users log in via Patreon, and acquire access and refresh tokens after logging in

require_once __DIR__.'/vendor/autoload.php';
 
use Patreon\API;
use Patreon\OAuth;

$client_id = '';      // Replace with your data
$client_secret = '';  // Replace with your data

// Set the redirect url where the user will land after oAuth. That url is where the access code will be sent as a _GET parameter. This may be any url in your app that you can accept and process the access code and login

// In this case, say, /patreon_login request uri

$redirect_uri = "http://mydomain.com/patreon_login";

// Generate the oAuth url

$href = 'https://www.patreon.com/oauth2/authorize?response_type=code&client_id=' 
. $client_id . '&redirect_uri=' . urlencode($redirect_uri);

// You can send an array of vars to Patreon and receive them back as they are. Ie, state vars to set the user state, app state or any other info which should be sent back and forth.

$state = array();
 
// For example lets set final page which the user needs to land at - this may be a content the user is unlocking via oauth, or a welcome/thank you page

// Lets make it a thank you page

$state['final_page'] = 'http://mydomain.com/thank_you';

// Add any number of vars you need to this array by $state['YOURKEY'] = VARIABLE

// Prepare state var. It must be json_encoded, base64_encoded and url encoded to be safe in regard to any odd chars
$state_parameters = '&state=' . urlencode( base64_encode( json_encode( $state ) ) );

// Append it to the url

$href .= $state_parameters;

// Now place the url into a login link. Below is a very simple login link with just text. in assets/images folder, there is a button image made with official Patreon assets (login_with_patreon.png). You can also use this image as the inner html of the <a> tag instead of the text provided here

// Scopes! You must request the scopes you need to have the access token.
// In this case, we are requesting the user's identity (basic user info), user's email
// For example, if you do not request email scope while logging the user in, later you wont be able to get user's email via /identity endpoint when fetching the user details
// You can only have access to data identified with the scopes you asked. Read more at https://docs.patreon.com/#scopes

// Lets request identity of the user, and email.

$scope_parameters = '&scope=identity%20identity'.urlencode('[email]');

$href .= $scope_parameters;

// Simply echoing it here. You can present the login link/button in any other way.

echo '<a href="'.$href.'">Click here to login via Patreon</a>';

// Up to this part we handled the way to prepare a login link for users to log in via Patreon oAuth using API v2. From this point on starts the processing of a logged in user or user returning from Patreon oAuth.

// The below code snippet needs to be active wherever the the user is landing in $redirect_uri parameter above. It will grab the auth code from Patreon and get the tokens via the oAuth client

if ( $_GET['code'] != '' ) {
	
	$oauth_client = new OAuth($client_id, $client_secret);	

	$tokens = $oauth_client->get_tokens($_GET['code'], $redirect_uri);
	
	$access_token = $tokens['access_token'];
	$refresh_token = $tokens['refresh_token'];
	
	// Here, you should save the access and refresh tokens for this user somewhere. Conceptually this is the point either you link an existing user of your app with his/her Patreon account, or, if the user is a new user, create an account for him or her in your app, log him or her in, and then link this new account with the Patreon account. More or less a social login logic applies here. 
	
	// Only use user's email address info coming from Patreon if the email is verified. Check for is_email_verified value in user's API return.
	
}

// After linking an existing account or a new account with Patreon by saving and matching the tokens for a given user, you can then read the access token (from the database or whatever resource), and then just check if the user is logged into Patreon by using below code. Code from down below can be placed wherever in your app, it doesnt need to be in the redirect_uri at which the Patreon user ends after oAuth. You just need the $access_token for the current user and thats it.

// Lets say you read $access_token for current user via db resource, or you just acquired it through oAuth earlier like the above - create a new API client

$api_client = new API($access_token);

// Return from the API can be received in either array, object or JSON formats by setting the return format. It defaults to array if not specifically set. Specifically setting return format is not necessary. Below is shown as an example of having the return parsed as an object. Default is array (associated) and there is no need to specifically set it if you are going to use it as an array. If there is anyone using Art4 JSON parser lib or any other parser, they can just set the API return to json and then have the return parsed by that parser

// You dont need the below line if you are going to use the return as array. 
$api_client->api_return_format = 'object';

// Now get the current user:

$patron_response = $api_client->fetch_user();

// At this point you can do anything with the user return. For example, if there is no return for this user, then you can consider the user not logged into Patreon. Or, if there is return, then you can get the user's Patreon id or pledge info. For example if you are able to acquire user's id, then you can consider the user logged into Patreon.