PHPackages                             github-php/sponsors - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. github-php/sponsors

AbandonedArchivedLibrary

github-php/sponsors
===================

A package for PHP to interact with GitHub Sponsors.

0.3.2(4y ago)985025[12 issues](https://github.com/driesvints/sponsors/issues)MITPHPPHP ^7.4|^8.0

Since Aug 25Pushed 4y ago4 watchersCompare

[ Source](https://github.com/driesvints/sponsors)[ Packagist](https://packagist.org/packages/github-php/sponsors)[ GitHub Sponsors](https://github.com/Gummibeer)[ GitHub Sponsors](https://github.com/driesvints)[ RSS](/packages/github-php-sponsors/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (5)Dependencies (5)Versions (6)Used By (0)

> Sadly, I have decided to abandon this project. Feel free to fork this repo if you want.
>
> \-- Dries

---

[![PHP GitHub Sponsors logo](/art/header.png)](/art/header.png)

PHP GitHub Sponsors
===================

[](#php-github-sponsors)

[ ![Tests](https://github.com/github-php/sponsors/workflows/Tests/badge.svg)](https://github.com/github-php/sponsors/actions?query=workflow%3ATests)[ ![Code Style](https://camo.githubusercontent.com/2f3e528094bbd59b55be82697239ed56783af3a5872438a3101c3020b8d24537/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3337313438383433342f736869656c643f7374796c653d666c6174)](https://github.styleci.io/repos/371488434)[ ![Latest Stable Version](https://camo.githubusercontent.com/1209b8a96c6155d882d8b7a5c14327e4861da09b179ea6ae9d6489fc9c44b7db/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6769746875622d7068702f73706f6e736f7273)](https://packagist.org/packages/github-php/sponsors)[ ![Total Downloads](https://camo.githubusercontent.com/18954b2c6038be228fdb8ccd1428cfa6a3cca62e54a92d4f15d598252676bc66/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6769746875622d7068702f73706f6e736f7273)](https://packagist.org/packages/github-php/sponsors)PHP GitHub Sponsors is a package that integrates directly with [the GitHub Sponsors GraphQL API](https://docs.github.com/en/sponsors/integrating-with-github-sponsors/getting-started-with-the-sponsors-graphql-api). Using it, you can easily check if a GitHub account is sponsoring another account. This helps you implement powerful ACL capabilities in your application and the ability to grant users access to specific resources when they sponsor you.

The library is PHP agnostic but provides deep integration with [Laravel](https://laravel.com).

Here's an example how you'd use it:

```
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();
```

Roadmap
-------

[](#roadmap)

Here's some of the features on our roadmap. We'd always appreciate PR's to kickstart these.

- [Caching](https://github.com/github-php/sponsors/issues/1)
- [Check sponsorship tiers](https://github.com/github-php/sponsors/issues/3)
- [Create new Sponsorships](https://github.com/github-php/sponsors/issues/5)
- [Automatically grant and revoke perks](https://github.com/github-php/sponsors/issues/7)
- [Sync sponsorships through GitHub webhooks](https://github.com/github-php/sponsors/issues/6)
- [Track sponsored amounts](https://github.com/github-php/sponsors/issues/8)

Not seeing the feature you seek? Consider opening up [an issue](https://github.com/github-php/sponsors/issues).

Requirements
------------

[](#requirements)

- PHP 7.4 or higher
- Laravel 8.0 or higher (optional when using Laravel)

Installation
------------

[](#installation)

Install the package with composer:

```
composer require github-php/sponsors
```

Updating
--------

[](#updating)

Please refer to [`the upgrade guide`](UPGRADE.md) when updating the library.

Configuration
-------------

[](#configuration)

### Authentication

[](#authentication)

All of the GitHub GraphQL autentication goes through a [personal access token](https://docs.github.com/en/graphql/guides/forming-calls-with-graphql#authenticating-with-graphql). A token is **always** needed when working with the GitHub GraphQL.

To get started using this library, head over to [your settings screen](https://github.com/settings/tokens) and create a personal access token that has access to the `user:read` and `org:read` scopes. This is the token that you'll use in the code examples below.

It's important to note that this will be the main point-of-view of how the GraphQL will view sponsorships so make sure to pick the correct user account. For example, if you're Laravel and you need to perform checks to see if anyone is sponsoring Laravel publically or privately, the token should be created under someone who has access to the Laravel organization (like `taylorotwell`).

#### Authentication in Laravel

[](#authentication-in-laravel)

If you're integrating with Laravel, the package will be set up automatically through Package Discovery. The only thing that's left to do is to set the personal access token in your `.env` file:

```
GH_SPONSORS_TOKEN=ghp_xxx

```

Usage
-----

[](#usage)

### Initializing the client

[](#initializing-the-client)

All of this library's API calls are made from the core `GitHub\Sponsors\Client` class. The client makes use of the [Illuminate HTTP Client](https://laravel.com/docs/http-client) client to perform the API calls. This client needs to be authenticated using the GitHub Personal Access token which you've created in the [authentication](#authentication) step above.

To get started, initialize the GitHub API client, authenticate using the token (preferable through an environment variable) and initialize the Sponsors client:

```
use GitHub\Sponsors\Client;

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

This will be the client we'll use throughout the rest of these docs. We'll re-use the `$client` variable in the below examples.

Additionally, you have two named constructors that you can use: `withEnv` that accepts an environment variable and `withToken` that accepts a token.

```
use GitHub\Sponsors\Client;

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

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

### Initializing the client using Laravel

[](#initializing-the-client-using-laravel)

If you're using Laravel, the client is already bound to the container as a singleton. Simply retrieve it from the container:

```
use GitHub\Sponsors\Client;

$client = app(Client::class);
```

The client was authenticated with the env variable you've set in your `.env` file.

### Checking Sponsorships

[](#checking-sponsorships)

At its core, this library allows you to easily check wether a specific user or organization is sponsoring another one:

```
// 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');
```

### Checking Sponsorships as a Viewer

[](#checking-sponsorships-as-a-viewer)

You can also perform these checks from the point-of-view of the user that was used to authenticate the GitHub API client. If you'll use the methods below, it would be as if you'd be browsing GitHub as the user that created the token.

```
// 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');
```

You might be wondering why we're using the "Viewer" wording here. "Viewer" is also a concept in the GraphQL API of GitHub. It represents the currently authenticated user that's performing the API requests. That's why we've decided to also use this terminology in the package's API.

### Checking Sponsorships with a Facade

[](#checking-sponsorships-with-a-facade)

If you use Laravel you can also make use of the shipped `GitHubSponsors` facade:

```
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');
```

### Retrieving Sponsors

[](#retrieving-sponsors)

You can also use the client to retrieve sponsorships:

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

This will return an instance of `Illuminate\Support\LazyCollection` which contains the lazy loaded sponsorships of the given account.

Additionally, you may retrieve additional fields that are available on the [User](https://docs.github.com/en/graphql/reference/objects#user) and [Organization](https://docs.github.com/en/graphql/reference/objects#organization) objects:

```
$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...
}
```

Lastly you may use the `hasSponsors` check to see if an account has any sponsors at all:

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

### Sponsorable Behavior

[](#sponsorable-behavior)

PHP GitHub Sponsors ships with a `Sponsorable` trait that can add sponsorable behavior to an object. Let's say you have a `User` object in your app. By letting that user provide a personal access token of their own, you can perform sponsorship checks on them as if they were browsing GitHub themselves.

#### The `Sponsorable` trait

[](#the-sponsorable-trait)

To get started, add the trait to any object you want to use it on and set the user's GitHub username and their personal access token:

```
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;
    }
}
```

Notice that we also added the `GitHub\Sponsors\Contracts\Sponsorable` to make sure the API is properly implemented on the `User` class.

The `$github_token` can be the same personal access token you use to initialize the `GitHub\Sponsors\Client` class but **if you also want to check private sponsorships on the user** you'll need them to provide you with their own token.

> ⚠️ Note that there is no check being performed on wether the github username and a user provided personal access token belong together. This is your own responsibility to do through [an API call to GitHub](https://docs.github.com/en/graphql/reference/queries#user).

#### Using the sponsorable

[](#using-the-sponsorable)

Now that we've configured our object, we can use it to perform GitHub Sponsors checks against:

```
$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();
```

#### Using the `Sponsorable` trait with Eloquent

[](#using-the-sponsorable-trait-with-eloquent)

If your sponsorable is an Eloquent model from Laravel, the setup differs a bit:

```
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;
}
```

What's important is that there's a `github` column (`string`) on the model's table. This column will need to have the GitHub username that belongs to the model.

With an Eloquent model, you also don't need to pass a personal access token. By default, it'll use the `GitHub\Sponsors\Client` class that's bound to the container. If you do want to identify the sponsorable to also check their private sponsorships you can add a `github_token` column (`string`) to the model's table and make sure the value is filled in. That way, all API requests will behave as if the user themselves is doing it.

> ⚠️ Note that there is no check being performed on wether the github username and a user provided personal access token belong together. This is your own responsibility to do through [an API call to GitHub](https://docs.github.com/en/graphql/reference/queries#user).

And then you can use the model as follows:

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

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

#### Customizing the Sponsorable properties

[](#customizing-the-sponsorable-properties)

If you want to customize the `$github` & `$github_token` property names you'll also need to update their getters:

```
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;
    }
}
```

#### Customizing the Sponsorable client

[](#customizing-the-sponsorable-client)

When providing the sponsorable with a token, it'll initialize a new GitHub client. You may also provide [the pre-set client](#initializing-the-client) if you wish:

```
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;
    }
}
```

Tutorials
---------

[](#tutorials)

### Usage in Laravel Policies

[](#usage-in-laravel-policies)

PHP GitHub Sponsors is an ideal way to grant your users access to certain resources in your app. Therefor, it's also an ideal candidate for a Laravel policy. For example, you could write a policy that grants access to a product when a user is sponsoring you.

First, you'll have to set [the `GH_SPONSORS_TOKEN` in your `.env` file](#initializing-the-client-using-laravel). This token needs to be created by the user that's being sponsored or a user that is a member of the organization that's being sponsored. Then, the client will be authenticated with this token.

Next, you'll need to [add the `Sponsorable` trait to your `User` model](#using-the-sponsorable-trait-with-eloquent). Additionally, you'll need to make sure that the `users` database has a `github` column (`VARCHAR(255)`) and all users have their GitHub usernames filled out.

Then, we'll write out policy. Let's say that we're creating this policy for Spatie:

```