flipboxfactory / patron
An OAuth2 Client for Craft CMS
Installs: 9 789
Dependents: 3
Suggesters: 0
Security: 0
Stars: 3
Watchers: 4
Forks: 2
Open Issues: 3
Type:craft-plugin
Requires
- php: >=8.0
- craftcms/cms: ~4.0
- flipboxfactory/craft-ember: ^3.0
- league/oauth2-client: ^2.4
- league/oauth2-facebook: ^2.0
- league/oauth2-github: ^2.0
- league/oauth2-google: ^2.0
- league/oauth2-instagram: ^2.0
- league/oauth2-linkedin: ^2.0
Requires (Dev)
- phpunit/phpunit: ^9.0
- squizlabs/php_codesniffer: ^3.2
This package is auto-updated.
Last update: 2024-10-14 04:23:23 UTC
README
Patron is an OAuth2 client manager; Providing an easy to use interface for managing OAuth2 providers and tokens.
Requirements
This plugin requires Craft CMS 3.0 or later.
Installation
Choose one of the following ways to add Patron to your project:
-
Composer:
Simply run the following command from your project root:
composer require flipboxfactory/patron
-
Craft CMS Plugin Store:
Within your Craft CMS project admin panel, navigate to the 'Plugin Store' and search for 'Patron'. Installation is a button click away.
Once the plugin is included in your project, navigate to the Control Panel, go to Settings → Plugins and click the “Install” button for Patron.
Features
Patron provides an Craft CMS admin interface for The PHP League's OAuth2 client package. Additional features include:
- Project Config compatible
- Provider locking (for plugin developers)
- Ships with native providers: Facebook, GitHub, Google, LinkedIn, Instagram
- Register your own OAuth2 Providers
Templating
The craft.patron
template variable provides access to the entire Patron plugin. However, there are two useful tags
worth highlighting:
Retrieving providers:
{% set providerQuery = craft.patron.providers %} {% set provider = providerQuery.handle('providerHandle').one() %}
Retrieving tokens:
{% set tokenQuery = craft.patron.tokens %} {% set token = tokenQuery.provider('providerHandle').one() %} {# a token associated to a provider #}
Screenshots
Settings
The settings (including provider configurations) can be overridden with the plugins configuration file: config/patron.php
It's recommended that sensitive data (such as the client secret) is accessed via environmental variables:
[ 'providerHandle' => [ 'clientId' => getenv('SOME_PROVIDER_CLIENT_ID'), 'clientSecret' => getenv('SOME_PROVIDER_CLIENT_SECRET'), ], 'anotherProviderHandle' => [ 'clientId' => getenv('SOME_OTHER_PROVIDER_CLIENT_ID'), 'clientSecret' => getenv('SOME_OTHER_PROVIDER_CLIENT_SECRET'), ] ]
Third Party Providers
Adding addition providers to Patron is handled through the following events:
-
Register a compatible The PHP League OAuth2 provider using a fully qualified class name. The PHP League has an extensive list that have been contributed by the community.
\yii\base\Event::on( \flipbox\patron\cp\Cp::class, \flipbox\patron\events\RegisterProviders::REGISTER_PROVIDERS, function (\flipbox\patron\events\RegisterProviders $event) { $event->providers[] = '\your\fully\qualified\provider\class\name'; // Ex: \Stevenmaguire\OAuth2\Client\Provider\Salesforce::class } );
-
[Optional] Register a settings interface for the Provider. If your provider can be configured, the settings interface will enable configuration inputs via the Craft CP. The settings interface will be registered on the same provider class in step 1.
\yii\base\Event::on( '\your\fully\qualified\provider\class\name', // Ex: \Stevenmaguire\OAuth2\Client\Provider\Salesforce::class \flipbox\patron\events\RegisterProviderSettings::REGISTER_SETTINGS, function (\flipbox\patron\events\RegisterProviderSettings $event) { $event->class = '\your\fully\qualified\settings\class\name'; // Ex: \flipbox\patron\salesforce\settings\SalesforceSettings::class } );
-
[Optional] Register additional info for the Provider. Throughout the Craft CP we use a provider
name
andicon
. Register the following in order to specify these values:\yii\base\Event::on( \flipbox\patron\cp\Cp::class, \flipbox\patron\events\RegisterProviderInfo::REGISTER_INFO, function (\flipbox\patron\events\RegisterProviderInfo $event) { $event->info['\your\fully\qualified\provider\class\name] = [ 'name' => 'Your Provider', 'icon' => '/path/to/icon.svg' // Ex: '@vendor/flipboxfactory/patron-salesforce/icons/salesforce.svg' ]; } );
As an example, here are a few third-party provider packages to reference:
Provider Locking
A provider can be 'locked' by a plugin. As a result, only the plugin (that locked it) can delete the provider. This is useful when another plugin is using Patron to manage it's OAuth2 connections, which may not be apparent.
```php
/** @var \flipbox\patron\records\Provider $provider */
/** @var \craft\base\PluginInterface $yourPlugin */
$provider->saveAndLock($yourPlugin);
```
Contributing
Please see CONTRIBUTING for details.
Credits
License
The MIT License (MIT). Please see License File for more information.