konsulting / laravel-butler
Butler manages multiple Socialite authentication for your Laravel app.
Requires
- php: ^7.1||^8.0
- laravel/framework: ^5.7 || ^6.0 || ^7.0 || ^8.0 || ^9.0
- laravel/legacy-factories: ^1.3
- laravel/socialite: ^4.0 || ^5.0
- nesbot/carbon: ^1.21 || ^2.0
Requires (Dev)
- mockery/mockery: ^1.2
- orchestra/database: ^4.0||^5.0||^6.0
- orchestra/testbench: ^4.0||^5.0||^6.0||^7.0
- orchestra/testbench-browser-kit: ^4.0||^5.0||^6.0||^7.0
- phpunit/phpunit: ^8.0
README
Butler manages multiple Socialite authentication for your Laravel app.
In a few simple steps you can allow users to log in to your site using multiple providers.
Butler is built to work alongside standard Laravel authentication, and uses Socialite to connect to authentication providers.
Requirements
-
Install Socialite - follow the documentation on the Laravel site.
-
Set up your Socialite providers (you may need to install extra Socialite Providers).
Installation
-
Install Butler using composer:
composer require konsulting/laravel-butler
-
If you are using Laravel 5.5, Butler will auto-register the service provider and the Facade. However, if you have chosen not to auto-register, or are using an earlier version, add Butler's Service Provider to
config/app.php
'providers' => [ // Other service providers... Konsulting\Butler\ButlerServiceProvider::class, ],
- Add Butler's Facade to
config/app.php
'aliases' => [ // Other aliases... 'Butler' => Konsulting\Butler\ButlerFacade::class, ],
- Add Butler's routes to
app/Providers/RouteServiceProvider.php
class RouteServiceProvider ... public function map() { $this->mapApiRoutes(); $this->mapWebRoutes(); \Butler::routes(); }
- Publish configuration and adjust for your site
php artisan vendor:publish --provider=Konsulting\\Butler\\ButlerServiceProvider --tag=config
Adjust in config/butler.php
. Add the providers you want to make available for Authentication - these map directly to Socialite drivers. There are examples in the published file.
// Other Settings 'providers' => [ 'google' => [ 'name' => 'Google', 'scopes' => [], // define any specific scopes you want to request here 'icon' => 'fa fa-google', 'class' => 'btn-google', ], ... ]
See configuration options for more information.
-
Optionally add list of Oauth buttons to your login page, and status feedback.
Add the following includes to your blade template for the login page.
@include('butler::status')
@include('butler::list')
Configuration Options
There is a small set of configuration options.
Butler Driver
We wrap the socialite driver in a Butler Driver which adds a methods to refresh()
a social identity using the refresh token.
It will also proxy all the usual SocialiteProvider methods to the orginal provider.
$driver = \Butler::driver(string $providerName); // For a specific social identity, this would be $socialIdentity->provider $driver->refresh($socialIdentity);
Security
We have not encrypted any of the retrieved tokens at this time, since the tokens are intended to be short-lived. We’re happy to receive views on this decision.
If you find any security issues, or have any concerns, please email keoghan@klever.co.uk, rather than using the issue tracker.
Contributing
Contributions are welcome and will be fully credited. We will accept contributions by Pull Request.
Please:
- Use the PSR-2 Coding Standard
- Add tests, if you’re not sure how, please ask.
- Document changes in behaviour, including readme.md.
Testing
We use PHPUnit and the excellent orchestral/testbench
Run tests using PHPUnit: vendor/bin/phpunit