README

遗憾的是，我已决定放弃这个项目。如果您想，请随意fork此仓库。

-- Dries 

PHP GitHub Sponsors

PHP GitHub Sponsors是一个直接集成GitHub Sponsors GraphQL API的包。使用它，您可以轻松检查一个GitHub账户是否在资助另一个账户。这有助于您在应用程序中实现强大的ACL功能，并在您被资助时授予用户访问特定资源的权限。

这个库对PHP是中立的，但提供了与Laravel的深度集成。

以下是一个使用示例

use GitHub\Sponsors\Client;

$client = new Client(getenv('GH_SPONSORS_TOKEN'));

// Check if driesvints is being sponsored by nunomaduro...
$client->login('driesvints')->isSponsoredBy('nunomaduro');

// Check if the authenticated user is sponsored by Gummibeer...
$client->viewer()->isSponsoredBy('Gummibeer');

// Check if the authenticated user is sponsoring driesvints...
$client->viewer()->isSponsoring('driesvints');

// Get all of the sponsors for Gummibeer...
$sponsors = $client->login('Gummibeer')->sponsors();

路线图

以下是我们的路线图上的一些功能。我们总是欢迎PR来启动这些功能。

• 缓存
• 检查赞助等级
• 创建新的赞助
• 自动授予和撤销特权
• 通过GitHub webhooks同步赞助
• 跟踪赞助金额

没有看到您想要的功能？请考虑打开问题。

要求

• PHP 7.4或更高版本
• Laravel 8.0或更高版本（使用Laravel时可选）

安装

使用composer安装此包

composer require github-php/sponsors

更新

在更新库时，请参阅升级指南。

配置

认证

所有GitHub GraphQL认证都通过个人访问令牌进行。当与GitHub GraphQL一起工作时，始终需要令牌。

要开始使用此库，请转到设置屏幕并创建一个具有访问user:read和org:read作用域的个人访问令牌。此令牌将用于下面的代码示例中。

请注意，这将成为GraphQL查看赞助的主要视角，所以请确保选择正确的用户账户。例如，如果您是Laravel，并且需要执行检查以查看是否有任何人公开或私下资助Laravel，则令牌应在可以访问Laravel组织（如taylorotwell）的人下创建。

Laravel中的认证

如果您正在与Laravel集成，该软件包将通过包发现自动设置。您需要做的唯一一件事是在您的.env文件中设置个人访问令牌

GH_SPONSORS_TOKEN=ghp_xxx

使用方法

初始化客户端

该库的所有API调用都是从核心类GitHub\Sponsors\Client开始的。客户端使用Illuminate HTTP Client来执行API调用。此客户端需要使用您在上述认证步骤中创建的GitHub个人访问令牌进行认证。

要开始，初始化GitHub API客户端，使用令牌（最好通过环境变量）进行认证，并初始化Sponsors客户端

use GitHub\Sponsors\Client;

$client = new Client(getenv('GH_SPONSORS_TOKEN'));

这将是我们在以下文档中使用的客户端。我们将在下面的示例中重新使用$client变量。

此外，您还可以使用两个命名构造函数：接受环境变量的withEnv和接受令牌的withToken。

use GitHub\Sponsors\Client;

$client = Client::withEnv('GH_SPONSORS_TOKEN');

$client = Client::withToken(getenv('GH_SPONSORS_TOKEN'));

使用Laravel初始化客户端

如果您正在使用Laravel，客户端已经作为单例绑定到容器中。只需从容器中检索它

use GitHub\Sponsors\Client;

$client = app(Client::class);

客户端已使用您在.env文件中设置的env变量进行了认证。

检查赞助

该库的核心功能允许您轻松检查特定用户或组织是否在赞助另一个组织

// Check if driesvints is being sponsored by nunomaduro...
$client->login('driesvints')->isSponsoredBy('nunomaduro');

// Check if the blade-ui-kit organization is being sponsored by nunomaduro...
$client->login('blade-ui-kit')->isSponsoredBy('nunomaduro');

作为观众检查赞助

您还可以从用于认证GitHub API客户端的用户的角度执行这些检查。如果您使用以下方法，就好像您正在以创建令牌的用户身份浏览GitHub一样。

// Is the current authed user sponsoring driesvints?
$client->viewer()->isSponsoring('driesvints');

// Is the current authed user sponsoring the laravel organization?
$client->viewer()->isSponsoring('laravel');

// Is the current authed user sponsored by driesvints?
$client->viewer()->isSponsoredBy('driesvints');

// Is the current authed user sponsored by the laravel organization?
$client->viewer()->isSponsoredBy('laravel');

您可能想知道为什么我们在这里使用“查看者”这个词。在GitHub的GraphQL API中，“查看者”也是一个概念。它代表当前进行API请求的已认证用户。这就是我们决定在包的API中也使用这个术语的原因。

使用外观检查赞助

如果您使用Laravel，您还可以使用随附的GitHubSponsors外观。

use GitHub\Sponsors\Facades\GitHubSponsors;

// Check if driesvints is being sponsored by nunomaduro...
GitHubSponsors::login('driesvints')->isSponsoredBy('nunomaduro');

// Check if the blade-ui-kit organization is being sponsored by nunomaduro...
GitHubSponsors::login('blade-ui-kit')->isSponsoredBy('nunomaduro');

检索赞助商

您还可以使用客户端检索赞助

$sponsors = $client->login('Gummibeer')->sponsors();

这将返回一个Illuminate\Support\LazyCollection实例，其中包含给定账户的懒加载赞助。

此外，您还可以检索用户和组织对象上可用的其他字段

$sponsors = $client->login('Gummibeer')->sponsors(['avatarUrl', 'name']);

foreach ($sponsors as $sponsor) {
    $sponsor['avatarUrl']; // The sponsor's GitHub avatar url...
    $sponsor['name']; // The sponsor's GitHub name...
}

最后，您可以使用hasSponsors检查来查看账户是否有任何赞助

if ($client->login('Gummibeer')->hasSponsors() {
    // ...
}

可赞助行为

PHP GitHub Sponsors附带一个Sponsorable特质，可以添加可赞助行为到对象中。假设您在应用程序中有一个User对象。通过让该用户提供他们自己的个人访问令牌，您可以在他们自己浏览GitHub时对他们的赞助进行检查。

可赞助特性

要开始使用，请将其添加到任何您想使用的对象上，并设置用户的GitHub用户名和他们的个人访问令牌

use GitHub\Sponsors\Concerns\Sponsorable;
use GitHub\Sponsors\Contracts\Sponsorable as SponsorableContract;

class User implements SponsorableContract
{
    use Sponsorable;

    private string $github;

    private string $github_token;

    public function __construct(string $github, string $github_token)
    {
        $this->github = $github;
        $this->github_token = $github_token;
    }
}

请注意，我们还添加了GitHub\Sponsors\Contracts\Sponsorable，以确保API在User类上正确实现。

$github_token可以与您用于初始化GitHub\Sponsors\Client类的相同个人访问令牌，但如果您还想要检查用户的私人赞助，则需要他们提供自己的令牌。

⚠️ 注意，我们不会检查GitHub用户名和用户提供的个人访问令牌是否属于同一用户。这是您自己的责任，通过GitHub API调用来完成。

使用可赞助特性

现在我们已经配置了我们的对象，我们可以使用它来对GitHub Sponsors进行检查

$user = new User('driesvints', getenv('GH_SPONSORS_TOKEN'));

// Check if driesvints is being sponsored by nunomaduro...
$user->isSponsoredBy('nunomaduro');

// Check if driesvints is being sponsored by the blade-ui-kit organization...
$user->isSponsoredBy('blade-ui-kit');

// Check if driesvints is sponsoring nunomaduro...
$user->isSponsoring('nunomaduro');

// Check if driesvints is sponsoring spatie...
$user->isSponsoring('spatie');

// Retrieve all of the sponsors for driesvints...
$sponsors = $user->sponsors();

// Check if driesvints has any sponsors...
$user->hasSponsors();

与Eloquent一起使用Sponsorable特性

如果您的可赞助对象是Laravel的Eloquent模型，则设置略有不同

use GitHub\Sponsors\Concerns\Sponsorable;
use GitHub\Sponsors\Contracts\Sponsorable as SponsorableContract;
use Illuminate\Database\Eloquent\Model;

class User extends Model implements SponsorableContract
{
    use Sponsorable;
}

重要的是，模型表中有一个github列（string）。这个列需要包含属于该模型的GitHub用户名。

对于Eloquent模型，您也不需要传递个人访问令牌。默认情况下，它将使用绑定到容器的GitHub\Sponsors\Client类。如果您想将可赞助对象识别为也要检查他们的私人赞助，可以向模型表添加一个github_token列（string）并确保其值已填写。这样，所有API请求都将表现得像是用户自己在执行。

⚠️ 注意，我们不会检查GitHub用户名和用户提供的个人访问令牌是否属于同一用户。这是您自己的责任，通过GitHub API调用来完成。

然后您可以使用该模型如下

$user = User::where('github', 'driesvints')->first();

// Check if driesvints is being sponsored by nunomaduro...
$user->isSponsoredBy('nunomaduro');

自定义可赞助属性

如果您想要自定义$github和$github_token属性名称，您还需要更新它们的getter方法

use GitHub\Sponsors\Concerns\Sponsorable;
use GitHub\Sponsors\Contracts\Sponsorable as SponsorableContract;

class User implements SponsorableContract
{
    use Sponsorable;

    private string $gitHubUsername;

    private string $gitHubToken;

    public function __construct(string $gitHubUsername, string $gitHubToken)
    {
        $this->gitHubUsername = $gitHubUsername;
        $this->gitHubToken = $gitHubToken;
    }

    public function gitHubUsername(): string
    {
        return $this->gitHubUsername;
    }

    public function gitHubToken(): ?string
    {
        return $this->gitHubToken;
    }
}

自定义可赞助客户端

当向可赞助对象提供一个令牌时，它将初始化一个新的GitHub客户端。如果您愿意，也可以提供预置的客户端。

use GitHub\Sponsors\Client;
use GitHub\Sponsors\Concerns\Sponsorable;
use GitHub\Sponsors\Contracts\Sponsorable as SponsorableContract;

class User implements SponsorableContract
{
    use Sponsorable;

    private Client $client;

    private string $github;

    public function __construct(Client $client, string $github)
    {
        $this->client = $client;
        $this->github = $github;
    }

    protected function sponsorsClient(): Client
    {
        return $this->client;
    }
}

教程

Laravel策略中的使用

PHP GitHub Sponsors是授予您的用户访问您应用程序中某些资源的理想方式。因此，它也是Laravel策略的理想候选者。例如，您可以编写一个策略，在用户赞助您时授予对产品的访问权限。

首先，您必须在您的.env文件中设置GH_SPONSORS_TOKEN。此令牌必须由被赞助的用户或组织赞助者的成员创建。然后，客户端将使用此令牌进行认证。

接下来，您需要将Sponsorable特性添加到您的User模型中。此外，您还需要确保数据库中的users有一个github列（VARCHAR(255)），并且所有用户的GitHub用户名都已填写。

然后，我们将编写策略。假设我们正在为Spatie创建此策略

<?php

namespace App\Policies;

use App\Models\User;

class ProductPolicy
{
    /**
     * Determine if a product can be reached by the user.
     *
     * @param  \App\Models\User  $user
     * @return bool
     */
    public function view(User $user)
    {
        return $user->isSponsoring('spatie');
    }
}

我们在应用程序的AuthServiceProvider中连接策略

use App\Models\Product;
use App\Policies\ProductPolicy;

/**
 * The policy mappings for the application.
 *
 * @var array
 */
protected $policies = [
    Product::class => ProductPolicy::class,
];

现在我们可以使用策略来执行ACL检查，查看认证用户是否可以访问Spatie的产品。

@can('view', App\Models\Product::class)
    <a href="{{ route('products') }}">
        View Products
    </a>
@else
    <a href="https://github.com/sponsors/spatie">
        Sponsor us to use our products!
    </a>
@endcan

就这些了。当然，你可能还想保护任何可以访问products路由的控制器。

常见问题解答

为什么赞助检查在私人赞助检查中返回false？

GitHub GraphQL的工作方式主要是通过个人访问令牌进行身份验证。因为这些令牌始终由GitHub中的特定用户创建，所以API调用将根据用户的可见性和对目标资源的访问权限返回结果。

例如，如果我以driesvints的身份私下赞助spatie，我可以进行一个->login('driesvints')->isSponsoredBy('spatie')检查，并且它将对我返回true，因为我可以通过在driesvints上创建的个人访问令牌访问我的账户。但如果是nunomaduro私下赞助spatie，而我使用在driesvints上创建的令牌尝试->login('nunomaduro')->isSponsoredBy('spatie')，它将返回false，因为我无法访问nunomaduro的账户。

如果你正在检查组织，也非常重要，你正在使用组织成员的令牌。任何其他GitHub用户都无法访问检查该组织的私人赞助。

尽管如此，公共赞助始终可见，无论令牌是在哪个用户上创建的。

为什么需要user:read和org:read作用域？

这两个作用域都需要来验证GitHub客户端以执行用户的私人赞助检查。由于默认情况下这些作用域对任何公共API调用都是隐藏的，我们需要明确授予令牌消费者读取这些权限的权限。

变更日志

请查看此存储库中的所有最近更改的变更日志。

维护者

PHP GitHub Sponsors是由Dries Vints和Tom Witkowski开发和维护的。

特别感谢Caneco为我们的标志✨

许可

PHP GitHub Sponsors是开源软件，许可协议为MIT许可。