Merge pull request #90 from bramr94/refactor-facade

WIP: Refactor facade
DutchCodingCompany · Jun 4, 2024 · fe414ad · fe414ad
2 parents 4b831ce + a2b27a9
commit fe414ad
Show file tree

Hide file tree

Showing 23 changed files with 850 additions and 510 deletions.
diff --git a/README.md b/README.md
@@ -14,11 +14,12 @@ Add OAuth2 login through Laravel Socialite to Filament. OAuth1 (eg. Twitter) is
 
 ## Installation
 
-| Filament version                                                                                                                                              | Package version |
-|---------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
-| [^3.2.44](https://github.com/filamentphp/filament/releases/tag/v3.2.44) (if using [SPA mode](https://filamentphp.com/docs/3.x/panels/configuration#spa-mode)) | ^1.3.1          |
-| 3.x                                                                                                                                                           | 1.x.x           |
-| 2.x                                                                                                                                                           | 0.x.x           |
+| Filament version                                                                                                                                               | Package version | Readme                                                                               |
+|----------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|--------------------------------------------------------------------------------------|
+| [^3.2.44](https://github.com/filamentphp/filament/releases/tag/v3.2.44) (if using [SPA mode](https://filamentphp.com/docs/3.x/panels/configuration#spa-mode))  | 2.x.x           | [Link](https://github.com/DutchCodingCompany/filament-socialite/blob/main/README.md) |
+| [^3.2.44](https://github.com/filamentphp/filament/releases/tag/v3.2.44) (if using [SPA mode](https://filamentphp.com/docs/3.x/panels/configuration#spa-mode))  | ^1.3.1          |                                                                                      |
+| 3.x                                                                                                                                                            | 1.x.x           | [Link](https://github.com/DutchCodingCompany/filament-socialite/blob/1.x/README.md)  |
+| 2.x                                                                                                                                                            | 0.x.x           |                                                                                      |
 
 Install the package via composer:
 
@@ -43,41 +44,44 @@ php artisan vendor:publish --tag="filament-socialite-translations"
 You need to register the plugin in the Filament panel provider (the default filename is `app/Providers/Filament/AdminPanelProvider.php`). The following options are available:
 
 ```php
+use DutchCodingCompany\FilamentSocialite\FilamentSocialitePlugin;
+use DutchCodingCompany\FilamentSocialite\Provider;
+use Filament\Support\Colors;
 use Laravel\Socialite\Contracts\User as SocialiteUserContract;
 use Illuminate\Contracts\Auth\Authenticatable;
 
 // ...
 ->plugin(
     FilamentSocialitePlugin::make()
         // (required) Add providers corresponding with providers in `config/services.php`. 
-        ->setProviders([
-            'github' => [
-                'label' => 'GitHub',
-                // Custom icon requires an additional package, see below.
-                'icon' => 'fab-github',
-                // (optional) Button color override, default: 'gray'.
-                'color' => 'primary',
-                // (optional) Button style override, default: true (outlined).
-                'outlined' => false,
-            ],
+        ->providers([
+            // Create a provider 'gitlab' corresponding to the Socialite driver with the same name.
+            Provider::make('gitlab')
+                ->label('GitLab')
+                ->icon('fab-gitlab')
+                ->color(Color::hex('#2f2a6b'))
+                ->outlined(false)
+                ->stateless(false)
+                ->scopes(['...'])
+                ->with(['...']),
         ])
         // (optional) Enable/disable registration of new (socialite-) users.
-        ->setRegistrationEnabled(true)
+        ->registration(true)
         // (optional) Enable/disable registration of new (socialite-) users using a callback.
         // In this example, a login flow can only continue if there exists a user (Authenticatable) already.
-        ->setRegistrationEnabled(fn (string $provider, SocialiteUserContract $oauthUser, ?Authenticatable $user) => (bool) $user)
+        ->registration(fn (string $provider, SocialiteUserContract $oauthUser, ?Authenticatable $user) => (bool) $user)
         // (optional) Change the associated model class.
-        ->setUserModelClass(\App\Models\User::class)
+        ->userModelClass(\App\Models\User::class)
         // (optional) Change the associated socialite class (see below).
-        ->setSocialiteUserModelClass(\App\Models\SocialiteUser::class)
+        ->socialiteUserModelClass(\App\Models\SocialiteUser::class)
 );
 ```
 
 See [Socialite Providers](https://socialiteproviders.com/) for additional Socialite providers.
 
 ### Icons
 
-You can specify a Blade Icon. You can add Font Awesome brand
+You can specify a custom icon for each of your login providers. You can add Font Awesome brand
 icons made available through [Blade Font Awesome](https://github.com/owenvoke/blade-fontawesome) by running:
 ```
 composer require owenvoke/blade-fontawesome
@@ -93,45 +97,51 @@ Or you could opt for customizing the user creation, see below.
 $table->string('password')->nullable();
 ```
 
-### Domain Allowlist
+### Domain Allow list
 
 This package supports the option to limit the users that can login with the OAuth login to users of a certain domain.
 This can be used to setup SSO for internal use.
 
 ```php
 ->plugin(
     FilamentSocialitePlugin::make()
-        ->setRegistrationEnabled(true)
-        ->setDomainAllowList(['localhost'])
+        // ...
+        ->registration(true)
+        ->domainAllowList(['localhost'])
 );
 ```
 
 ### Changing how an Authenticatable user is created or retrieved
 
-In your AppServiceProvider.php, add in the boot method:
+You can use the `createUserUsing` and `resolveUserUsing` methods to change how a user is created or retrieved.
+
 ```php
-use DutchCodingCompany\FilamentSocialite\Facades\FilamentSocialite as FilamentSocialiteFacade;
-use DutchCodingCompany\FilamentSocialite\FilamentSocialite;
+use DutchCodingCompany\FilamentSocialite\FilamentSocialitePlugin;
 use Laravel\Socialite\Contracts\User as SocialiteUserContract;
 
-// Default
-FilamentSocialiteFacade::setCreateUserCallback(fn (string $provider, SocialiteUserContract $oauthUser, FilamentSocialite $socialite) => $socialite->getUserModelClass()::create([
-    'name' => $oauthUser->getName(),
-    'email' => $oauthUser->getEmail(),
-]));
-
-FilamentSocialiteFacade::setUserResolver(fn (string $provider, SocialiteUserContract $oauthUser, FilamentSocialite $socialite) => /* ... */);
+->plugin(
+    FilamentSocialitePlugin::make()
+        // ...
+        ->createUserUsing(function (string $provider, SocialiteUserContract $oauthUser, FilamentSocialitePlugin $plugin) {
+            // Logic to create a new user.
+        })
+        ->resolveUserUsing(function (string $provider, SocialiteUserContract $oauthUser, FilamentSocialitePlugin $plugin) {
+            // Logic to retrieve an existing user.
+        })
+        ...
+);
 ```
 
 ### Change how a Socialite user is created or retrieved
 
 In your plugin options in your Filament panel, add the following method:
+
 ```php
 // app/Providers/Filament/AdminPanelProvider.php
 ->plugins([
     FilamentSocialitePlugin::make()
         // ...
-        ->setSocialiteUserModelClass(\App\Models\SocialiteUser::class)
+        ->socialiteUserModelClass(\App\Models\SocialiteUser::class)
 ```
 
 This class should at the minimum implement the [`FilamentSocialiteUser`](/src/Models/Contracts/FilamentSocialiteUser.php) interface, like so:
@@ -168,17 +178,17 @@ class SocialiteUser implements FilamentSocialiteUserContract
 ### Change login redirect
 
 When your panel has [multi-tenancy](https://filamentphp.com/docs/3.x/panels/tenancy) enabled, after logging in, the user will be redirected to their [default tenant](https://filamentphp.com/docs/3.x/panels/tenancy#setting-the-default-tenant).
-If you want to change this behavior, you can add the `setLoginRedirectCallback` method in the boot method of your `AppServiceProvider.php`:
+If you want to change this behavior, you can call the 'redirectAfterLoginUsing' method on the `FilamentSocialitePlugin`.
 
 ```php
+use DutchCodingCompany\FilamentSocialite\FilamentSocialitePlugin;
 use DutchCodingCompany\FilamentSocialite\Models\Contracts\FilamentSocialiteUser as FilamentSocialiteUserContract;
 use DutchCodingCompany\FilamentSocialite\Models\SocialiteUser;
 
-FilamentSocialite::setLoginRedirectCallback(function (string $provider, FilamentSocialiteUserContract $socialiteUser) {
-    return redirect()->intended(
-        route(FilamentSocialite::getPlugin()->getDashboardRouteName())
-    );
-});
+FilamentSocialitePlugin::make()
+    ->redirectAfterLoginUsing(function (string $provider, FilamentSocialiteUserContract $socialiteUser, FilamentSocialitePlugin $plugin) {
+        // Change the redirect behaviour here.
+    });
 ```
 
 ### Filament Fortify
@@ -229,33 +239,44 @@ There are a few events dispatched during the authentication process:
 
 ## Scopes
 
-Scopes should be added in your `config/services.php` config file, for example:
+Scopes can be added to the provider on the panel, for example:
 
 ```php
-'github' => [
-    'client_id' => '...',
-    'client_secret' => '...',
-    'scopes' => [
-        // Add scopes here.
-        'read:user',
-        'public_repo',
-    ],
-]
+use DutchCodingCompany\FilamentSocialite\FilamentSocialitePlugin;
+use DutchCodingCompany\FilamentSocialite\Provider;
+
+FilamentSocialitePlugin::make()
+    ->providers([
+        Provider::make('github')
+            ->label('Github')
+            ->icon('fab-github')
+            ->scopes([
+                // Add scopes here.
+                'read:user',
+                'public_repo',
+            ]),
+    ]),
 ```
 
 ## Optional parameters
 
-You can add [optional parameters](https://laravel.com/docs/10.x/socialite#optional-parameters) to the request by adding a `with` key to the provider configuration in the `config/services.php` config file, for example:
+You can add [optional parameters](https://laravel.com/docs/10.x/socialite#optional-parameters) to the request by adding a `with` key to the provider on the panel, for example:
 
 ```php
-'github' => [
-    'client_id' => '...',
-    'client_secret' => '...',
-    'with' => [
-        // Add optional parameters here
-        'hd' => 'example.com',
-    ],
-]
+use DutchCodingCompany\FilamentSocialite\FilamentSocialitePlugin;
+use DutchCodingCompany\FilamentSocialite\Provider;
+
+FilamentSocialitePlugin::make()
+    ->providers([
+        Provider::make('github')
+            ->label('Github')
+            ->icon('fab-github')
+            ->with([
+                // Add scopes here.
+                // Add optional parameters here.
+                'hd' => 'example.com',
+            ]),
+    ]),
 ```
 
 ## Stateless Authentication

diff --git a/UPGRADE.md b/UPGRADE.md
@@ -1,4 +1,124 @@
 # Upgrade Guide
+## `1.x.x` to `2.x.x` (Filament v3.x)
+
+For version 2 we refactored most of the plugin to be more consistent with the Filament naming conventions. We've also moved some of the callbacks to the plugin, so they are configurable per panel.
+
+### Method names
+
+Every method name has been changed to be more consistent with the Filament naming conventions. The following changes have been made:
+
+- `setProviders()` -> `providers()` 
+- `setSlug()` -> `slug()` 
+- `setLoginRouteName()` -> `loginRouteName()` 
+- `setDashboardRouteName()` -> `dashboardRouteName()` 
+- `setRememberLogin()` -> `rememberLogin()` 
+- `setRegistrationEnabled()` -> `registration()` 
+- `getRegistrationEnabled()` -> `getRegistration()` 
+- `setDomainAllowList()` -> `domainAllowList()` 
+- `setSocialiteUserModelClass()` -> `socialiteUserModelClass()`
+- `setUserModelClass()` -> `userModelClass()` 
+- `setShowDivider()` -> `showDivider()` 
+
+**Note:** We've included a simple rector script which automatically updates the method names. It checks all panel providers in the `app\Provider\Filament` directory. You can run the script by executing the following command:
+
+```bash
+vendor/bin/upgrade-v2
+```
+#### Callbacks
+
+**setCreateUserCallback()**
+
+The `setCreateUserCallback()` has been renamed to `createUserUsing()`. This function was first registered in the `boot` method of your `AppServiceProvider.php`, but now it should be called on the plugin.
+
+```php
+FilamentSocialitePlugin::make()
+    // ...
+    ->createUserUsing(function (string $provider, SocialiteUserContract $oauthUser, FilamentSocialitePlugin $plugin) {
+        // Logic to create a new user.
+    })
+```
+
+**setUserResolver()**
+
+The `setUserResolver()` has been renamed to `resolveUserUsing()`. This function was first registered in the `boot` method of your `AppServiceProvider.php`, but now it should be called on the plugin.
+
+```php
+FilamentSocialitePlugin::make()
+    // ...
+    ->resolveUserUsing(function (string $provider, SocialiteUserContract $oauthUser, FilamentSocialitePlugin $plugin) {
+        // Logic to retrieve an existing user.
+    })
+```
+
+**setLoginRedirectCallback()**
+
+The `setLoginRedirectCallback()` has been renamed to `redirectAfterLoginUsing()`. This function was first registered in the `boot` method of your `AppServiceProvider.php`, but now it should be called on the plugin.
+
+```php
+FilamentSocialitePlugin::make()
+    // ...
+    ->redirectAfterLoginUsing(function (string $provider, FilamentSocialiteUserContract $socialiteUser, FilamentSocialitePlugin $plugin) {
+        // Change the redirect behaviour here.
+    })
+```
+
+#### Removals
+
+**getOptionalParameters()**
+
+This function was used internally only inside the `SocialiteLoginController`. If you haven't extended this controller, you can ignore this change.
+
+Provider details can now be retrieved using `$plugin->getProvider($provider)->getWith()`.
+
+**getProviderScopes()**
+
+This function was used internally only inside the `SocialiteLoginController`. If you haven't extended this controller, you can ignore this change.
+
+Provider details can now be retrieved using `$plugin->getProvider($provider)->getScopes()`.
+
+### Configuration
+
+**Providers**
+
+Previously, providers were configured by passing a plain array. In the new setup, they should be created using the `Provider` class. The key should be passed as part of the `make()` function.
+
+```php
+use DutchCodingCompany\FilamentSocialite\FilamentSocialitePlugin;
+use DutchCodingCompany\FilamentSocialite\Provider;
+
+FilamentSocialitePlugin::make()
+    ->providers([
+        Provider::make('gitlab')
+            ->label('GitLab')
+            ->icon('fab-gitlab')
+            ->color(Color::hex('#2f2a6b')),
+    ]),
+```
+
+**Scopes and Optional parameters**
+
+Scopes and additional parameters for Socialite providers were previously configured in the `services.php` file, but have now been moved to the `->providers()` method on the Filament plugin.
+
+```php
+use DutchCodingCompany\FilamentSocialite\FilamentSocialitePlugin;
+use DutchCodingCompany\FilamentSocialite\Provider;
+
+FilamentSocialitePlugin::make()
+    ->providers([
+        Provider::make('gitlab')
+            // ...
+            ->scopes([
+                // Add scopes here.
+                'read:user',
+                'public_repo',
+            ]),
+            ->with([
+                // Add optional parameters here.
+                 'hd' => 'example.com',
+            ]),
+    ]),
+```
+
 ## `0.x.x` to `1.x.x` (Filament v3.x)
 - Replace/republish the configuration file:
   - `sail artisan vendor:publish --provider="DutchCodingCompany\FilamentSocialite\FilamentSocialiteServiceProvider"`

diff --git a/bin/upgrade-v2 b/bin/upgrade-v2
@@ -0,0 +1,6 @@
+#!/usr/bin/env php
+<?php
+
+namespace Composer;
+
+exec("vendor/bin/rector process --config vendor/dutchcodingcompany/filament-socialite/rector.php --clear-cache");
diff --git a/composer.json b/composer.json
@@ -37,7 +37,8 @@
         "larastan/larastan": "^2.9",
         "nunomaduro/collision": "^7.0|^8.1",
         "orchestra/testbench": "^8.0|^9.0",
-        "phpunit/phpunit": "^10.0"
+        "phpunit/phpunit": "^10.0",
+        "rector/rector": "^0.19.8"
     },
     "suggest": {
         "owenvoke/blade-fontawesome": "^2.0"
@@ -46,13 +47,17 @@
         "psr-4": {
             "DutchCodingCompany\\FilamentSocialite\\": "src",
             "DutchCodingCompany\\FilamentSocialite\\Tests\\": "tests",
-            "DutchCodingCompany\\FilamentSocialite\\Database\\Factories\\": "database/factories"
+            "DutchCodingCompany\\FilamentSocialite\\Database\\Factories\\": "database/factories",
+            "Utils\\Rector\\": "utils/rector/src"
         }
     },
     "scripts": {
         "analyse": "vendor/bin/phpstan analyse",
         "test": "vendor/bin/phpunit"
     },
+    "bin": [
+        "bin/upgrade-v2"
+    ],
     "config": {
         "sort-packages": true,
         "allow-plugins": {