more-cores / laravel-restcord
Requires
- php: >=7.3.0
- illuminate/contracts: >=6.0
- illuminate/support: >=6.0
- laravel/socialite: ^4.0 || ^5.0
- restcord/restcord: dev-master
Requires (Dev)
- codeclimate/php-test-reporter: ^0.4
- mockery/mockery: ^1.0
- phpunit/phpunit: 8.*
- satooshi/php-coveralls: ^1.0
- socialiteproviders/discord: 2.*
- symfony/var-dumper: ^4.0
- vlucas/phpdotenv: ^3.3
Suggests
- socialiteproviders/discord: Bootstraps Restcord's API library with the currently OAuth'd user
README
A small, fluent wrapper for Restcord.
THIS PROJECT IS DEPRECATED, see https://gitlab.com/more-cores/laravel-restcord/-/issues/38 for more details.
README Contents
Features
- Integrates Restcord with Laravel Socialite so currently OAuth'd user is used for api calls (when
sessionHasDiscordToken
middleware is used) - Handles creation of webhooks via OAuth (no bot required)
- Handles adding bots to to guilds via OAuth (no websocket connection required)
- Obtain information about a member's relationship with a guild (roles, permissions, etc.)
Installation
- Install package
composer require more-cores/laravel-restcord:2.*
- Define the
DISCORD_BOT_TOKEN
environmental variable. - Add the middleware
sessionHasDiscordToken
for the routes where you need to use the current OAuth'd user's credentials to interact with the Discord API. This is required because session information is not available in a ServiceProvider.
- For Laravel <= 5.4, register the service provider in
config/app.php
'providers' => [
...
LaravelRestcord\ServiceProvider::class,
]
Environment Variables
DISCORD_BOT_KEY
DISCORD_BOT_SECRET
DISCORD_BOT_TOKEN
DISCORD_KEY
DISCORD_SECRET
Bot key/secret will be used for callback endpoints related to adding a bot or creating a webhook as well as when the application is running in the console such as queue workers and cron.
Usage
This documentation assumes your users are logging in via the Discord driver for Laravel Socialite.
Anytime you see $discord
in this documentation it is assumed to be an instance of LaravelRestcord\Discord\Discord::class
which is available from Laravel's IOC container.
Guilds
Get a list of guilds the current user has access to:
$discord->guilds() // Guild[]
Get information about a user's relationship with a guild
$guild->userCan(Permission::KICK_MEMBERS); // bool - uses permissions of the currently oauth'd user
$member = $guild->getMemberById($discordUserId); // \LaravelRestcord\Discord\Member
$member->roles(); // \LaravelRestcord\Discord\Role[]
$member->joinedAt(); // Carbon
Adding Bots To Guilds
This implementation uses the Advanced Bot Authorization flow to add the bot to a guild. You should have the Require OAuth2 Code Grant option enabled on your app's settings.
use LaravelRestcord\Discord\HandlesBotAddedToGuild;
use Illuminate\Http\RedirectResponse;
class BotAddedToDiscordGuild
{
use HandlesBotAddedToGuild;
public function botAdded(Guild $guild) : RedirectResponse
{
// do something with the guild information the bot was added to
return redirect('/to/this/page');
}
}
Next, add a binding to your AppServiceProvider
so the package knows which class to pass the guild information to when the user returns to your web site.
$this->app->bind(HandlesBotAddedToGuild::class, BotAddedToDiscordGuild::class);
Now you're ready to direct the user to Discord's web site so they can select the guild to add the bot to:
public function show(Guild $guild)
{
// Reference https://discordapi.com/permissions.html to determine
// the permissions your bot needs
$guild->sendUserToDiscordToAddBot($permissions);
}
This package handles the routing needs, but you need to whitelist the callback URL for this to work. Add http://MY-SITE.com/discord/bot-added
to your application's redirect uris.
Your handler will be trigger when the bot has been added to a guild.
> You will be able to send messages via this bot once it has established a web socket connection. It only has to do this once, so it's a common practice to use the below code snippet to do so:
"use strict";
var TOKEN="PUT YOUR TOKEN HERE";
fetch("https://discord.com/api/v7/gateway").then(function(a){return a.json()}).then(function(a){var b=new WebSocket(a.url+"/?encoding=json&v=6");b.onerror=function(a){return console.error(a)},b.onmessage=function(a){try{var c=JSON.parse(a.data);0===c.op&&"READY"===c.t&&(b.close(),console.log("Successful authentication! You may now close this window!")),10===c.op&&b.send(JSON.stringify({op:2,d:{token:TOKEN,properties:{$browser:"b1nzy is a meme"},large_threshold:50}}))}catch(a){console.error(a)}}});
Creating Webhooks
Because we're using OAuth to create webhooks, the user will be directed to Discord's web site to select the guild/channel. This package handles interpreting the request/response lifecycle for this, so all you need to do is build a handler:
use LaravelRestcord\Discord\HandlesDiscordWebhooksBeingCreated;
use Illuminate\Http\RedirectResponse;
class Subscribe
{
use HandlesDiscordWebhooksBeingCreated;
public function webhookCreated(Webhook $webhook) : RedirectResponse
{
// $webhook->token();
// Here you should save the token for use later when activating the webhook
return redirect('/to/this/page');
}
}
Next, add a binding to your AppServiceProvider
so the package knows which class to pass the webhook data to when the user returns to your web site.
$this->app->bind(HandlesDiscordWebhooksBeingCreated::class, DiscordChannelAdded::class);
Now you're ready to direct the user to Discord's web site to create the webhook:
public function show(Guild $guild)
{
// redirects the user to Discord's interface for selecting
// a guild and channel for the webhook
$guild->sendUserToDiscordToCreateWebhook();
}
This package handles the routing needs, but you need to whitelist the callback URL for this to work. Add http://MY-SITE.com/discord/create-webhook
to your application's redirect uris.
Your handler will be trigger when the webhook is created.