matthew-jensen / laravel-discourse
PHP Discourse Forum API for the Laravel Framework
Requires (Dev)
- orchestra/testbench: ^3.8
This package is auto-updated.
Last update: 2024-04-29 04:00:33 UTC
README
Version Compatibility
Laravel | Discourse Client |
---|---|
> 5.8.x | Untested |
5.8.x | 0.0.2 |
Getting Started
Before going through the rest of this documentation, please take some time to read the Discourse API Documentation. Not all of the API calls are documented, but it's a good place to start. Additional help with SSO: https://meta.discourse.org
Installation
To install through composer, simply put the following in your composer.json
file:
{ "require": { "matthew-jensen/laravel-discourse-client": "^0.0.2" } }
And then run composer install
from the terminal.
Add the following to config/app.php:
/* * $APP_PATH/config/app.php */ 'providers' => [ MatthewJensen\LaravelDiscourse\DiscourseServiceProvider::class ],
You can optionally publish the config file with:
php artisan vendor:publish --provider="MatthewJensen\LaravelDiscourse\DiscourseServiceProvider" --tag="config"
This is the contents of the published config file:
<?php return [ // API token. 'token' => env('DISCOURSE_TOKEN') // Middleware for the SSO login route to use 'middleware' => ['web', 'auth'], // The route's URI that acts as the entry point for Discourse to start the SSO process. // Used by Discourse to route incoming logins. 'route' => 'discourse/sso', 'logout' => 'discourse/sso/logout', // Secret string used to encrypt/decrypt SSO information, // be sure that it is 10 chars or longer 'secret' => env('DISCOURSE_SECRET'), // Disable Discourse from sending welcome message 'suppress_welcome_message' => 'true', // Where the Discourse forum lives 'url' => env('DISCOURSE_URL'), // User-specific items // NOTE: The 'email' & 'external_id' are the only 2 required fields 'user' => [ // Check to see if the user has forum access & should be logged in via SSO 'access' => null, // Discourse Groups to make sure that the user is part of in a comma-separated string // NOTE: Groups cannot have spaces in their names & must already exist in Discourse 'add_groups' => null, // Boolean for making the user a Discourse admin. Leave null to ignore 'admin' => 'discourse_admin', // Full path to user's avatar image 'avatar_url' => null, // The avatar is cached, so this triggers an update 'avatar_force_update' => false, // Content of the user's bio 'bio' => null, // Verified email address (see "require_activation" if not verified) 'email' => 'email', // Unique string for the user that will never change 'external_id' => 'id', // Boolean for making user a Discourse moderator. Leave null to ignore 'moderator' => 'discourse_moderator', // Full name on Discourse if the user is new or // if SiteSetting.sso_overrides_name is set 'name' => 'name', // Discourse Groups to make sure that the user is *NOT* part of in a comma-separated string. // NOTE: Groups cannot have spaces in their names & must already exist in Discourse // There is not a way to specify the exact list of groups that a user is in, so // you may want to send the inverse of the 'add_groups' 'remove_groups' => null, // If the email has not been verified, set this to true 'require_activation' => false, // username on Discourse if the user is new or // if SiteSetting.sso_overrides_username is set 'username' => 'email', ], ];
Configure Laravel Discourse
Laravel Env
Set the API Token, Forum url and SSO Token in your .env:
DISCOURSE_URL=https://forum.url
DISCOURSE_SECRET={sso secret}
DISCOURSE_TOKEN={api token}
Discourse Env
Enable SSO Via UI: see: "{DISCOURSE_URL}/admin/site_settings/category/required?filter="
Via console:
cd /var/discourse ./launcher enter app rails c irb > SiteSetting.sso_secret = {config('discourse.secret')} irb > SiteSetting.sso_url = {config('discourse.route')} irb > SiteSetting.logout_redirect = {config('discourse.logout')} irb > SiteSetting.enable_sso = true irb > SiteSetting.enable_local_logins = false irb > exit exit
TODO
- Artisan command to set sso secret, route and enable sso to install out of the box (could be done via API calls in Facade).
Credits
SSO Helper Methods: cviebrock/discourse-php.
SSO Controller Methods: spinen/laravel-discourse-sso.
API Methods: discoursehosting/discourse-api-php.