Filament Socialite

https://github.com/dutchcodingcompany/filament-socialite
Admin
Filament Socialite is a package that adds OAuth2 login functionality through Laravel Socialite to...
Tokens:58,255
Snippets:432
Trust Score:6.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Provider Configuration Examples

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/provider.md

Examples of configuring a provider with basic and dynamic options.

```APIDOC
## Provider Configuration Example

### Description
Shows how to configure a provider with basic options such as label, icon, color, outlined, stateless, scopes, and with parameters.

### Example
```php
use DutchCodingCompany\FilamentSocialite\Provider;
use Filament\Support\Colors\Color;

Provider::make('gitlab')
    ->label('GitLab')
    ->icon('fab-gitlab')
    ->color(Color::hex('#2f2a6b'))
    ->outlined(false)
    ->stateless(false)
    ->scopes(['read_user', 'api'])
    ->with(['hd' => 'example.com']);
```
```

```APIDOC
## Conditional Visibility Example

### Description
Shows how to conditionally show a provider using closures for visibility, scopes, and with parameters.

### Example
```php
use DutchCodingCompany\FilamentSocialite\Provider;

Provider::make('github')
    ->visible(fn () => app()->environment('production'))
    ->scopes(fn (Provider $provider) => $provider->getName() === 'github' ? ['public_repo'] : [])
    ->with(fn () => ['prompt' => 'select_account']);
```
```

--------------------------------

### Install via Composer

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/README.md

Install the package using Composer.

```bash
composer require dutchcodingcompany/filament-socialite
```

--------------------------------

### Example direct usage with error handling

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/socialite-login-controller.md

Example of calling processCallback directly, catching ProviderNotConfigured. The response is either a redirect to the panel or back to the login page.

```php
use DutchCodingCompany\FilamentSocialite\Exceptions\ProviderNotConfigured;
use DutchCodingCompany\FilamentSocialite\Http\Controllers\SocialiteLoginController;
use Illuminate\Http\Request;

$controller = app(SocialiteLoginController::class);

try {
    $response = $controller->processCallback('github');
} catch (ProviderNotConfigured $e) {
    // 'github' is missing from providers() or config/services.php
    report($e);
}
// $response is either a redirect to the panel or back to the login page
```

--------------------------------

### OAuth callback URL example

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/README.md

Example callback URL for external OAuth app configuration.

```text
https://example.com/admin/oauth/callback/github
```

--------------------------------

### Example route for redirectToProvider

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/socialite-login-controller.md

Example route that calls redirectToProvider directly. Useful for custom redirect endpoints.

```php
use Illuminate\Support\Facades\Route;

Route::get('/custom/redirect/{provider}', function (string $provider) {
    return app(\DutchCodingCompany\FilamentSocialite\Http\Controllers\SocialiteLoginController::class)
        ->redirectToProvider($provider);
});
```

--------------------------------

### Basic provider configuration

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/provider.md

Basic provider configuration example for GitLab, showing label, icon, color, and OAuth options.

```php
use DutchCodingCompany\FilamentSocialite\Provider;
use Filament\Support\Colors\Color;

Provider::make('gitlab')
    ->label('GitLab')
    ->icon('fab-gitlab')
    ->color(Color::hex('#2f2a6b'))
    ->outlined(false)
    ->stateless(false)
    ->scopes(['read_user', 'api'])
    ->with(['hd' => 'example.com']);
```

--------------------------------

### GET|POST /oauth/callback/{provider}

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/endpoints.md

Documentation for the multi-panel OAuth callback route that handles both GET and POST requests.

```APIDOC
## [GET|POST] /oauth/callback/{provider}

### Description
Handles the OAuth callback for multiple Filament panels. It uses the `state` query parameter to determine which panel should handle the callback, allowing several panels to share a single OAuth application and callback URL.

### Method
`GET`, `POST`

### Endpoint
`/oauth/callback/{provider}`

### Parameters
#### Path Parameters
- **provider** (string) - Required - The OAuth provider name (e.g., `google`, `github`).

#### Query Parameters
- **state** (string) - Required - A string that decrypts under `Laravel\Illuminate\Support\Facades\Crypt` to the panel ID. Must be produced by `redirectToProvider`. If absent or undecryptable, an `InvalidCallbackPayload` exception is thrown (HTTP 500).

### Request Example
```
GET /oauth/callback/google?state=encrypted-panel-id
```

### Response
#### Success Response (200)
- Redirects to the appropriate panel's page after successful authentication.

#### Error Responses
- **500** - `InvalidCallbackPayload` when the `state` payload cannot be decrypted.
- Other failures are the same as route 2 (not specified in this source).

### Notes
- This route only works for **stateful** OAuth providers that echo the `state` parameter back. For stateless providers, use the `$slug/oauth/callback/{provider}` route instead.
- All panels sharing this URL must have the plugin registered.
- The route is public and CSRF-exempt.
- Middleware: `PanelFromUrlQuery` (first) + `config('filament-socialite.middleware')`.
- Route name: `oauth.callback`.
```

--------------------------------

### Implement FilamentSocialiteUser contract

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/README.md

Example implementation of the `FilamentSocialiteUser` contract. This class must implement `getUser`, `findForProvider`, and `createForProvider` methods.

```php
namespace App\Models;

use DutchCodingCompany\FilamentSocialite\Models\Contracts\FilamentSocialiteUser as FilamentSocialiteUserContract;
use Illuminate\Contracts\Auth\Authenticatable;
use Laravel\Socialite\Contracts\User as SocialiteUserContract;

class SocialiteUser implements FilamentSocialiteUserContract
{
    public function getUser(): Authenticatable
    {
        //
    }

    public static function findForProvider(string $provider, SocialiteUserContract $oauthUser): ?self
    {
        //
    }
    
    public static function createForProvider(
        string $provider,
        SocialiteUserContract $oauthUser,
        Authenticatable $user
    ): self {
        //
    }
}
```

--------------------------------

### ProviderNotConfigured

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/errors.md

Documentation for the ProviderNotConfigured exception, including its factory method and usage example.

```APIDOC
## `ProviderNotConfigured`

### Description
Exception thrown when a socialite provider is not configured. It is a subclass of `LogicException` and can be created via the static factory `make(string $provider): self`.

### Factory Method
`ProviderNotConfigured::make(string $provider): self`

### Parameters
- **$provider** (string) - Required - The name of the provider that is not configured.

### Throws
- **ProviderNotConfigured** - When the provider is not configured in `config/services.php` or on the panel.

### Usage Example
```php
use DutchCodingCompany\FilamentSocialite\Exceptions\ProviderNotConfigured;

try {
    $provider = $plugin->getProvider('twitter');
} catch (ProviderNotConfigured $e) {
    // Provider "twitter" is not configured...
    report($e);
}
```
```

--------------------------------

### Add optional parameters to a provider

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/README.md

Add optional parameters to the OAuth request using the with method. The example passes 'hd' => 'example.com' to the GitHub provider.

```php
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',
            ]),
    ]),
```

--------------------------------

### Catch ProviderNotConfigured when getting a provider

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/errors.md

Example of catching `ProviderNotConfigured` when calling `getProvider('twitter')`. The catch block reports the exception and can handle the missing configuration. The comment shows the exception message format.

```php
use DutchCodingCompany\FilamentSocialite\Exceptions\ProviderNotConfigured;

try {
    $provider = $plugin->getProvider('twitter');
} catch (ProviderNotConfigured $e) {
    // Provider "twitter" is not configured...
    report($e);
}
```

--------------------------------

### Install Blade Font Awesome for icons

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/README.md

Install Blade Font Awesome to use Font Awesome brand icons for login providers. Run this command in your project root.

```bash
composer require owenvoke/blade-fontawesome
```

--------------------------------

### GuardNotStateful

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/errors.md

Documentation for the GuardNotStateful exception, including its factory method and usage example.

```APIDOC
## `GuardNotStateful`

### Description
Exception thrown when the panel's authentication guard is not stateful. It is a subclass of `LogicException` and can be created via the static factory `make(string $guard): self`.

### Factory Method
`GuardNotStateful::make(string $guard): self`

### Parameters
- **$guard** (string) - Required - The name of the guard that is not stateful.

### Throws
- **GuardNotStateful** - When the guard does not implement `Illuminate\Contracts\Auth\StatefulGuard`.

### Usage Example
```php
use DutchCodingCompany\FilamentSocialite\Exceptions\GuardNotStateful;

try {
    $guard = $plugin->getGuard();
} catch (GuardNotStateful $e) {
    // Panel 'admin' uses a non-stateful guard; OAuth login cannot be performed.
}
```
```

--------------------------------

### Provider::label(string $label): static / getLabel(): string

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/provider.md

Sets or gets the button text label. Defaults to title-cased provider name.

```APIDOC
## Provider::label(string $label): static / getLabel(): string

### Description
Sets the button label or retrieves the current label. Default is `Str::title($this->getName())`.

### Method
Fluent setter / Getter

### Parameters (setter)
- **$label** (string) - Required - The button text.

### Return Value (getter)
- **string** - The button label.

### Example
php
$provider->label('GitHub');
$label = $provider->getLabel();

```

--------------------------------

### Provider::outlined(bool $outlined = true): static / getOutlined(): bool

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/provider.md

Sets or gets whether the button renders outlined. Default is true.

```APIDOC
## Provider::outlined(bool $outlined = true): static / getOutlined(): bool

### Description
Sets the outlined flag or retrieves the current value. Default is `true`.

### Method
Fluent setter / Getter

### Parameters (setter)
- **$outlined** (bool) - Optional - Whether the button is outlined. Defaults to `true`.

### Return Value (getter)
- **bool** - Whether the button is outlined.

### Example
php
$provider->outlined(false);
$isOutlined = $provider->getOutlined();

```

--------------------------------

### Direct usage of SocialiteUser model

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/socialite-user.md

Example of querying the SocialiteUser model directly to find an existing link and to link an existing user to a provider.

```php
use DutchCodingCompany\FilamentSocialite\Models\SocialiteUser;

// Find an existing link (used by the default findForProvider)
$link = SocialiteUser::findForProvider('github', $oauthUser);

if ($link) {
    $appUser = $link->getUser(); // Illuminate\Contracts\Auth\Authenticatable
    $providerName = $link->provider; // 'github'
    $providerUid = $link->provider_id;
}

// Link an existing user to a provider
$link = SocialiteUser::createForProvider('github', $oauthUser, $user);
```

--------------------------------

### Provider fill() bulk configurator

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/provider.md

Bulk configurator that calls the fluent method named by each array key. For example, ['label' => 'GitHub'] calls label('GitHub'). Returns the instance for chaining.

```php
/**
 * @param array<string, mixed> $attributes
 */
public function fill(array $attributes): static
{
    foreach ($attributes as $key => $value) {
        $this->{$key}($value);
    }

    return $this;
}
```

--------------------------------

### userModelClass() and getUserModelClass() methods

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Methods to set and get the application user model class. The class must implement `Authenticatable`. Default is `\App\Models\User::class`.

```php
/**
 * @param class-string<\Illuminate\Contracts\Auth\Authenticatable> $value
 */
public function userModelClass(string $value): static

/**
 * @return class-string<\Illuminate\Contracts\Auth\Authenticatable>
 */
public function getUserModelClass(): string // default: \App\Models\User::class
```

--------------------------------

### Provider::name(string $name): static / getName(): string

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/provider.md

Sets or gets the provider name used as map key, route parameter, and Socialite driver name.

```APIDOC
## Provider::name(string $name): static / getName(): string

### Description
Sets the provider name or retrieves the current name.

### Method
Fluent setter / Getter

### Parameters (setter)
- **$name** (string) - Required - The provider name.

### Return Value (getter)
- **string** - The provider name.

### Example
php
$provider->name('github');
$name = $provider->getName();

```

--------------------------------

### socialiteUserModelClass() and getSocialiteUserModelClass() methods

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Methods to set and get the socialite user model class. The class must implement the `FilamentSocialiteUser` contract. Default is `DutchCodingCompany\FilamentSocialite\Models\SocialiteUser::class`.

```php
/**
 * @param class-string<\DutchCodingCompany\FilamentSocialite\Models\Contracts\FilamentSocialiteUser> $value
 */
public function socialiteUserModelClass(string $value): static

/**
 * @return class-string<\DutchCodingCompany\FilamentSocialite\Models\Contracts\FilamentSocialiteUser>
 */
public function getSocialiteUserModelClass(): string // default: DutchCodingCompany\FilamentSocialite\Models\SocialiteUser::class
```

--------------------------------

### loginRouteName() and getLoginRouteName() methods

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Methods to set and get the login route name. The default is the panel's generated route name for 'auth.login'. The user is redirected to this route when the callback fails.

```php
public function loginRouteName(string $value): static
public function getLoginRouteName(): string // default: $this->getPanel()->generateRouteName('auth.login')
```

--------------------------------

### register(Panel $panel) / boot(Panel $panel)

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Filament lifecycle hooks for registration and booting.

```APIDOC
## register(Panel $panel) / boot(Panel $panel)

### Description
Filament lifecycle hooks. `register` stores the panel ID (`$this->panelId = $panel->getId()`), which is later required by `getPanelId()`; `boot` is a no-op.

### Methods
- `public function register(Panel $panel): void`
- `public function boot(Panel $panel): void`

### Source
`src/FilamentSocialitePlugin.php:76`, `:81`

```

--------------------------------

### Catch GuardNotStateful when getting the guard

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/errors.md

Example of catching `GuardNotStateful` when calling `getGuard()`. The catch block handles the case where the panel uses a non-stateful guard, preventing OAuth login. The comment illustrates the scenario.

```php
use DutchCodingCompany\FilamentSocialite\Exceptions\GuardNotStateful;

try {
    $guard = $plugin->getGuard();
} catch (GuardNotStateful $e) {
    // Panel 'admin' uses a non-stateful guard; OAuth login cannot be performed.
}
```

--------------------------------

### Publish and migrate migrations

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/README.md

Publish the migration file and run migrations.

```bash
php artisan vendor:publish --tag="filament-socialite-migrations"
php artisan migrate
```

--------------------------------

### Publish other configuration files

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/README.md

Publish config, views, and translations.

```bash
php artisan vendor:publish --tag="filament-socialite-config"
php artisan vendor:publish --tag="filament-socialite-views"
php artisan vendor:publish --tag="filament-socialite-translations"
```

--------------------------------

### Basic registration with FilamentSocialitePlugin

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Configure a Filament panel with a GitHub socialite provider, enabling registration and restricting allowed domains to example.com.

```php
use DutchCodingCompany\FilamentSocialite\FilamentSocialitePlugin;
use DutchCodingCompany\FilamentSocialite\Provider;
use Filament\Support\Colors\Color;

->plugin(
    FilamentSocialitePlugin::make()
        ->providers([
            Provider::make('github')
                ->label('GitHub')
                ->icon('fab-github')
                ->color(Color::hex('#24292f')),
        ])
        ->registration(true)
        ->domainAllowList(['example.com'])
)
```

--------------------------------

### handle(Request $request, Closure $next)

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/panel-from-url-query.md

Middleware entry point that decrypts the panel ID from the `state` query parameter and sets up the current Filament panel.

```APIDOC
## `handle(Request $request, Closure $next)`

### Description
Middleware entry point. Decrypts the panel ID from the `state` query parameter and delegates to Filament's `SetUpPanel` middleware to set up the current panel for the request cycle.

### Method
`handle`

### Parameters
- **$request** (Request) - Required - The incoming HTTP request.
- **$next** (Closure) - Required - The next middleware in the pipeline.

### Return Value
- **mixed** - The response from the next middleware.

### Throws
- **InvalidCallbackPayload** - If the `state` input is missing, not a string, or cannot be decrypted.

### Source
`src/Http/Middleware/PanelFromUrlQuery.php:19`
```

--------------------------------

### rememberLogin(bool $value) / getRememberLogin()

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Sets and gets whether to pass 'remember' to the guard during login.

```APIDOC
## rememberLogin(bool $value) / getRememberLogin()

### Description
Sets and gets whether to pass "remember" to the guard during login.

### Methods
- `rememberLogin(bool $value): static`
- `getRememberLogin(): bool` (default: false)

### Parameters
- `$value` (bool) - Required - Whether to remember the login.

### Return
- `rememberLogin`: static
- `getRememberLogin`: bool
```

--------------------------------

### register() and boot() lifecycle hooks

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Filament lifecycle hooks. register stores the panel ID, boot is a no-op.

```php
public function register(Panel $panel): void
public function boot(Panel $panel): void
```

--------------------------------

### configurePackage() method

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/service-provider.md

Declares the package's publishables and assets for spatie/laravel-package-tools. This method is called by the package tools during registration.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('filament-socialite')
        ->hasConfigFile()
        ->hasTranslations()
        ->hasViews()
        ->hasRoute('web')
        ->hasMigration('create_socialite_users_table');
}
```

--------------------------------

### Provider::icon(string|null $icon): static / getIcon(): string|null

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/provider.md

Sets or gets the Blade icon rendered on the button.

```APIDOC
## Provider::icon(string|null $icon): static / getIcon(): string|null

### Description
Sets the icon or retrieves the current icon. Default is `null`.

### Method
Fluent setter / Getter

### Parameters (setter)
- **$icon** (string|null) - Required - The Blade icon name.

### Return Value (getter)
- **string|null** - The icon name or null.

### Example
php
$provider->icon('fab-github');
$icon = $provider->getIcon();

```

--------------------------------

### GET /{slug}/oauth/{provider}

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/endpoints.md

OAuth redirect endpoint that initiates the Socialite authentication flow for a given provider.

```APIDOC
## GET /{slug}/oauth/{provider}

### Description
Redirects the user to the OAuth provider for authentication. The provider must be configured in `config/services.php` and registered via the plugin's `providers()` method.

### Method
GET

### Endpoint
`/{slug}/oauth/{provider}` where `{slug}` is the plugin slug (defaults to the panel path, e.g., `admin` for `/admin`).

### Parameters
#### Path Parameters
- **provider** (string) - Required - Socialite driver name; must be in `config/services.php` and registered via `providers()` on the plugin.

#### Query Parameters
- **any key of provider `with`** (mixed) - Optional - Merged into the redirect destination.
- **state** (string) - Optional - Overwritten server-side with encrypted panel ID; never pass your own.

### Response
#### Success Response (302)
Redirect to the OAuth provider's authorization URL.

#### Error Response (500)
If the provider is not configured (uncaught `ProviderNotConfigured`).
```

--------------------------------

### Configure providers with Provider class

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/UPGRADE.md

Providers are now configured using the Provider class instead of a plain array. The key is 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')),
    ]),
```

--------------------------------

### Custom SocialiteUser model implementing contract

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/socialite-user.md

Example of a custom model that implements the FilamentSocialiteUser contract, with placeholder method bodies.

```php
namespace App\Models;

use DutchCodingCompany\FilamentSocialite\Models\Contracts\FilamentSocialiteUser as FilamentSocialiteUserContract;
use Illuminate\Contracts\Auth\Authenticatable;
use Laravel\Socialite\Contracts\User as SocialiteUserContract;

class SocialiteUser implements FilamentSocialiteUserContract
{
    public function getUser(): Authenticatable { /* ... */ }

    public static function findForProvider(string $provider, SocialiteUserContract $oauthUser): ?self { /* ... */ }

    public static function createForProvider(string $provider, SocialiteUserContract $oauthUser, Authenticatable $user): self { /* ... */ }
}
```

--------------------------------

### Provider::__construct(string $name)

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/provider.md

Constructor that sets the provider name.

```APIDOC
## Provider::__construct(string $name)

### Description
Creates a new Provider instance with the given name.

### Method
Constructor

### Parameters
- **$name** (string) - Required - The provider name, must correspond to a Socialite driver configured in `config/services.php`.

### Example
php
new Provider('github');

```

--------------------------------

### Models::socialiteUserModelClass(string $value) / getSocialiteUserModelClass()

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Sets and gets the class implementing the FilamentSocialiteUser contract used to store the provider-user link.

```APIDOC
## socialiteUserModelClass(string $value) / getSocialiteUserModelClass()

### Description
Sets and gets the class implementing the `FilamentSocialiteUser` contract used to store the provider↔user link.

### Methods
- `socialiteUserModelClass(string $value): static` - Sets the socialite user model class.
- `getSocialiteUserModelClass(): string` - Returns the socialite user model class. Default: `DutchCodingCompany\FilamentSocialite\Models\SocialiteUser::class`.

### Parameters
#### socialiteUserModelClass
- **$value** (class-string<\DutchCodingCompany\FilamentSocialite\Models\Contracts\FilamentSocialiteUser>) - Required - The socialite user model class name.

### Return Value
- **static** - Returns the instance for chaining (setter).
- **string** - The socialite user model class name (getter).

### Source
`src/Traits/Models.php:42`, `:52`
```

--------------------------------

### current() static method

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Returns the plugin instance of the currently active Filament panel. Throws ImplementationException if the current panel is null or does not have the plugin registered.

```php
public static function current(): static
```

--------------------------------

### domainAllowList(array $values) / getDomainAllowList()

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Sets and gets the list of allowed email domains. An empty list allows all email domains.

```APIDOC
## domainAllowList(array $values) / getDomainAllowList()

### Description
List of allowed email domains (lowercase, without `@`). An empty list allows all email domains. Consumed by the default `authorizeUserUsing` callback (see `Callbacks`).

### Methods
- `domainAllowList(array $values): static`
- `getDomainAllowList(): array` (default: [])

### Parameters
- `$values` (array<string>) - Required - List of allowed email domains.

### Return
- `domainAllowList`: static
- `getDomainAllowList`: array
```

--------------------------------

### Configure createUserUsing() callback

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/UPGRADE.md

Replaces the old setCreateUserCallback() method. This callback should now be called on the plugin instead of being registered in the boot method of AppServiceProvider.php.

```php
FilamentSocialitePlugin::make()
    // ...
    ->createUserUsing(function (string $provider, SocialiteUserContract $oauthUser, FilamentSocialitePlugin $plugin) {
        // Logic to create a new user.
    })
```

--------------------------------

### Models::userModelClass(string $value) / getUserModelClass()

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Sets and gets the class of the application user model. The class must implement the Authenticatable contract.

```APIDOC
## userModelClass(string $value) / getUserModelClass()

### Description
Sets and gets the class of the application user model. The class must implement the `Authenticatable` contract.

### Methods
- `userModelClass(string $value): static` - Sets the user model class.
- `getUserModelClass(): string` - Returns the user model class. Default: `\App\Models\User::class`.

### Parameters
#### userModelClass
- **$value** (class-string<\Illuminate\Contracts\Auth\Authenticatable>) - Required - The user model class name.

### Return Value
- **static** - Returns the instance for chaining (setter).
- **string** - The user model class name (getter).

### Source
`src/Traits/Models.php:24`, `:34`
```

--------------------------------

### Handle missing plugin with try-catch

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/buttons.md

Handles a missing plugin gracefully in PHP by catching ImplementationException and skipping button rendering.

```php
use DutchCodingCompany\FilamentSocialite\Exceptions\ImplementationException;
use DutchCodingCompany\FilamentSocialite\FilamentSocialitePlugin;

try {
    $plugin = FilamentSocialitePlugin::current();
} catch (ImplementationException $e) {
    // Panel without filament-socialite: skip rendering buttons entirely
    return;
}
```

--------------------------------

### Publish package assets

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/service-provider.md

Publishes the package's assets (migrations, config, views, translations) and runs migrations. The provider is auto-registered, so no manual registration is needed.

```bash
php artisan vendor:publish --tag="filament-socialite-migrations"
php artisan vendor:publish --tag="filament-socialite-config"
php artisan vendor:publish --tag="filament-socialite-views"
php artisan vendor:publish --tag="filament-socialite-translations"
php artisan migrate
```

--------------------------------

### Handle request in PanelFromUrlQuery middleware

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/panel-from-url-query.md

Middleware entry point. Decrypts the panel ID from the 'state' query parameter and delegates to Filament's SetUpPanel middleware with the decrypted panel ID as its third argument. Throws InvalidCallbackPayload if 'state' is missing, not a string, or cannot be decrypted.

```php
public function handle(Request $request, Closure $next): mixed
{
    // Set the current panel based on the encrypted panel name in the url query.
    return (new SetUpPanel())->handle($request, $next, static::decrypt($request));
}
```

--------------------------------

### GET|POST /{slug}/oauth/callback/{provider}

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/endpoints.md

Documentation for the OAuth callback endpoint that handles provider redirects.

```APIDOC
## GET|POST /{slug}/oauth/callback/{provider}

### Description
Handles the OAuth callback from the provider. This is the URL to configure as the OAuth app's callback URL. It processes the authorization code and state, authenticates the user, and redirects to the panel or tenant.

### Method
GET, POST

### Endpoint
/{slug}/oauth/callback/{provider}

### Parameters
#### Path Parameters
- **provider** (string) - Required - The OAuth provider identifier (e.g., `github`).

#### Query Parameters
- **code** (string) - Required - OAuth authorization code appended by the provider.
- **state** (string) - Required - Echoed back by the provider; must match the session value for stateful providers. Socialite verifies it; on mismatch `InvalidState` event fires and the user is redirected to login.

#### Request Body (POST)
- **code** (string) - Required - Provider-echoed form data.
- **state** (string) - Required - Provider-echoed form data.

### Request Example
```
POST /{slug}/oauth/callback/{provider}
Content-Type: application/x-www-form-urlencoded

code=abc123&state=xyz789
```

### Response
#### Success Response (302)
- **Location** (string) - Redirect to the panel URL, or with tenancy, to the user's default tenant (or tenant registration URL when none).

#### Response Example
```
HTTP/1.1 302 Found
Location: https://example.com/admin
```

#### Failure Responses (302 redirects to login route, with message flashed in session)
- **Condition**: OAuth user retrieval returned null (invalid state captured) - Flash key: `filament-socialite-login-error` - Message: `filament-socialite::auth.login-failed`
- **Condition**: Authorization failed (`authorizeUserUsing` false / domain not allowed) - Flash key: `filament-socialite-login-error` - Message: `filament-socialite::auth.user-not-allowed`
- **Condition**: Registration disabled/denied and no existing user link - Flash key: `filament-socialite-login-error` - Message: `filament-socialite::auth.registration-not-enabled`

#### Error Responses (exceptions thrown)
- **Provider not configured** - Status: 500 - Exception: `ProviderNotConfigured`
- **Panel guard is not stateful** - Status: 500 - Exception: `GuardNotStateful`
- **ImplementationException** (no current panel/plugin, null email in domain check) - Status: 500 - Exception: `ImplementationException`
```

--------------------------------

### SocialiteUserConnected event class

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/events.md

Dispatched by SocialiteLoginController::registerSocialiteUser() when an existing app user gets linked to a provider (createForProvider), before loginUser(). Source: src/Events/SocialiteUserConnected.php:13

```php
class SocialiteUserConnected
{
    use Dispatchable;
    use SerializesModels;

    public function __construct(
        public string $provider,
        public SocialiteUserContract $oauthUser,
        public FilamentSocialiteUserContract $socialiteUser,
    ) {
    }
}
```

--------------------------------

### Constructor with config and auth dependencies

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

The constructor is resolved from the container by make() and is not normally invoked directly. It injects the config repository and auth factory.

```php
public function __construct(
    protected Repository $config, // Illuminate\Contracts\Config\Repository
    protected Factory $auth,       // Illuminate\Contracts\Auth\Factory
) {
    //
}
```

--------------------------------

### Routes::dashboardRouteName(string $value) / getDashboardRouteName()

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Sets and gets the route name of the panel dashboard. This is retained for API compatibility and not used elsewhere in the package.

```APIDOC
## dashboardRouteName(string $value) / getDashboardRouteName()

### Description
Sets and gets the route name of the panel dashboard. This is retained for API compatibility and not used elsewhere in the package.

### Methods
- `dashboardRouteName(string $value): static` - Sets the dashboard route name.
- `getDashboardRouteName(): string` - Returns the dashboard route name. Default: `$this->getPanel()->generateRouteName('pages.dashboard')`.

### Parameters
#### dashboardRouteName
- **$value** (string) - Required - The route name to set.

### Return Value
- **static** - Returns the instance for chaining (setter).
- **string** - The dashboard route name (getter).

### Source
`src/Traits/Routes.php:28`, `:35`
```

--------------------------------

### Multi-panel OAuth callback route with PanelFromUrlQuery

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/endpoints.md

Defines the multi-panel OAuth callback route. It uses the `state` query input to determine the Filament panel, so multiple panels can share one OAuth application. Requires a stateful OAuth provider and the plugin registered on all panels sharing the URL.

```php
Route::match(['get', 'post'], "/oauth/callback/{provider}", [SocialiteLoginController::class, 'processCallback'])
    ->middleware([
        PanelFromUrlQuery::class,
        ...config('filament-socialite.middleware'),
    ])
    ->name('oauth.callback');
```

--------------------------------

### stateless(bool $stateless = true) / getStateless()

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/provider.md

Methods to enable or disable stateless OAuth authentication and retrieve the current setting.

```APIDOC
## stateless(bool $stateless = true) / getStateless()

### Description
Controls whether the OAuth state verification is skipped in the callback. When true, `Socialite::driver(...)->stateless()->user()` is used, useful for providers configured stateless in `config/services.php` (e.g. Apple).

### Method
stateless(bool $stateless = true): static

getStateless(): bool

### Parameters
- **$stateless** (bool) - Optional - Whether to skip OAuth state verification. Defaults to `true`.

### Returns
- **stateless()**: static - The provider instance for chaining.
- **getStateless()**: bool - The current stateless flag, defaulting to `false`.

### Example
```php
$provider->stateless();
$isStateless = $provider->getStateless();
```
```

--------------------------------

### Catching ImplementationException

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/errors.md

Example of catching ImplementationException when calling FilamentSocialitePlugin::current(). The catch block reports the exception and handles the case where the current panel is not a filament-socialite panel.

```php
use DutchCodingCompany\FilamentSocialite\Exceptions\ImplementationException;

try {
    $plugin = FilamentSocialitePlugin::current();
} catch (ImplementationException $e) {
    // current panel is not a filament-socialite panel
    report($e);
}

```

--------------------------------

### Configure registration and domain allow list

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/README.md

Enable registration and restrict OAuth logins to users from a specific domain. This is useful for setting up SSO for internal use.

```php
->plugin(
    FilamentSocialitePlugin::make()
        // ...
        ->registration(true)
        ->domainAllowList(['localhost'])
);
```

--------------------------------

### registerOauthUser() - Create user and socialite link in transaction

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/socialite-login-controller.md

Creates a new app user and its socialite link atomically in one DB::transaction, then dispatches Events\Registered and logs in.

```php
protected function registerOauthUser(string $provider, SocialiteUserContract $oauthUser): Response
{
    $socialiteUser = DB::transaction(function () use ($provider, $oauthUser) {
        $user = app()->call($this->plugin()->getCreateUserUsing(), ['provider' => $provider, 'oauthUser' => $oauthUser, 'plugin' => $this->plugin]);

        return $this->plugin()->getSocialiteUserModel()::createForProvider($provider, $oauthUser, $user);
    });

    Events\Registered::dispatch($provider, $oauthUser, $socialiteUser);

    return $this->loginUser($provider, $socialiteUser, $oauthUser);
}
```

--------------------------------

### Add scopes to a provider

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/README.md

Add OAuth scopes to a provider on the panel using the scopes method. The example adds 'read:user' and 'public_repo' scopes to the GitHub provider.

```php
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',
            ]),
    ]),
```

--------------------------------

### Republish configuration file

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/UPGRADE.md

Run this artisan command to republish the configuration file for the Filament Socialite package.

```bash
sail artisan vendor:publish --provider="DutchCodingCompany\FilamentSocialite\FilamentSocialiteServiceProvider"
```

--------------------------------

### Routes::loginRouteName(string $value) / getLoginRouteName()

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Sets and gets the route name the user is redirected to when the callback fails. The default value is the panel's auth.login route name.

```APIDOC
## loginRouteName(string $value) / getLoginRouteName()

### Description
Sets and gets the route name the user is redirected to when the callback fails. The default value is the panel's auth.login route name.

### Methods
- `loginRouteName(string $value): static` - Sets the login route name.
- `getLoginRouteName(): string` - Returns the login route name. Default: `$this->getPanel()->generateRouteName('auth.login')`.

### Parameters
#### loginRouteName
- **$value** (string) - Required - The route name to set.

### Return Value
- **static** - Returns the instance for chaining (setter).
- **string** - The login route name (getter).

### Source
`src/Traits/Routes.php:16`, `:23`
```

--------------------------------

### Configure redirectAfterLoginUsing() callback

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/UPGRADE.md

Replaces the old setLoginRedirectCallback() method. This callback should now be called on the plugin instead of being registered in the boot method of AppServiceProvider.php.

```php
FilamentSocialitePlugin::make()
    // ...
    ->redirectAfterLoginUsing(function (string $provider, FilamentSocialiteUserContract $socialiteUser, FilamentSocialitePlugin $plugin) {
        // Change the redirect behaviour here.
    })
```

--------------------------------

### Buttons render() method

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/buttons.md

Renders the buttons view with providers, visibleProviders, socialiteRoute, and messageBag. Pulls the flashed 'filament-socialite-login-error' session value into a MessageBag under 'login-failed' (one-shot).

```php
/**
 * @inheritDoc
 */
public function render()
{
    $messageBag = new MessageBag();

    if (session()->has('filament-socialite-login-error')) {
        $messageBag->add('login-failed', session()->pull('filament-socialite-login-error'));
    }

    return view('filament-socialite::components.buttons', [
        'providers' => $providers = $this->plugin->getProviders(),
        'visibleProviders' => array_filter($providers, fn (Provider $provider) => $provider->isVisible()),
        'socialiteRoute' => $this->plugin->getRoute(),
        'messageBag' => $messageBag,
    ]);
}
```

--------------------------------

### Manually decrypt panel ID with error handling

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/panel-from-url-query.md

Example of manually invoking PanelFromUrlQuery::decrypt with error handling. Catches InvalidCallbackPayload and aborts with a 400 response using the exception message.

```php
use DutchCodingCompany\FilamentSocialite\Exceptions\InvalidCallbackPayload;
use DutchCodingCompany\FilamentSocialite\Http\Middleware\PanelFromUrlQuery;

try {
    $panelId = PanelFromUrlQuery::decrypt($request); // e.g. 'admin'
    // $request->input('state') was a valid, decryptable string
} catch (InvalidCallbackPayload $e) {
    // state was absent, not a string, or corrupt
    abort(400, $e->getMessage());
}
```

--------------------------------

### createUserUsing and getCreateUserUsing callbacks

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Defines the callback for creating a new application user when none exists. The default implementation creates a user with name and email from the OAuth user, requiring the password column to be nullable unless overridden.

```php
/**
 * @param ?\Closure(string $provider, \Laravel\Socialite\Contracts\User $oauthUser, \DutchCodingCompany\FilamentSocialite\FilamentSocialitePlugin $plugin): \Illuminate\Contracts\Auth\Authenticatable $callback
 */
public function createUserUsing(?Closure $callback = null): static

/**
 * @return \Closure(string $provider, \Laravel\Socialite\Contracts\User $oauthUser, \DutchCodingCompany\FilamentSocialite\FilamentSocialitePlugin $plugin): \Illuminate\Contracts\Auth\Authenticatable
 */
public function getCreateUserUsing(): Closure
```

```php
$query = (new $this->userModelClass())->query();

return $query->create([
    'name' => $oauthUser->getName(),
    'email' => $oauthUser->getEmail(),
]);
```

--------------------------------

### with(Closure | array $with) / getWith()

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/provider.md

Methods to set and retrieve optional query parameters for the OAuth redirect.

```APIDOC
## with(Closure | array $with) / getWith()

### Description
Sets or retrieves optional query parameters merged into the OAuth redirect (`Socialite::driver(...)->with(...)`). Closures are evaluated with the provider instance as context.

### Method
with(Closure | array $with): static

getWith(): array

### Parameters
- **$with** (Closure | array) - Required - The query parameters to merge into the OAuth redirect. A closure returning an array of parameters or an array of parameters.

### Returns
- **with()**: static - The provider instance for chaining.
- **getWith()**: array - The current query parameters, defaulting to `[]`.

### Example
```php
$provider->with(['hd' => 'example.com']);
$with = $provider->getWith();
```
```

--------------------------------

### dashboardRouteName() and getDashboardRouteName() methods

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Methods to set and get the dashboard route name. The default is the panel's generated route name for 'pages.dashboard'. Not used elsewhere in the package; retained for API compatibility.

```php
public function dashboardRouteName(string $value): static
public function getDashboardRouteName(): string // default: $this->getPanel()->generateRouteName('pages.dashboard')
```

--------------------------------

### registration(Closure | bool $value = true) / getRegistration()

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/filament-socialite-plugin.md

Controls whether unknown users may be registered. Accepts a boolean or a closure evaluated with $provider, $oauthUser, and $user.

```APIDOC
## registration(Closure | bool $value = true) / getRegistration()

### Description
Controls whether unknown users (no existing socialite-user record and no resolved user) may be registered. The setter default is `true`, but the property default is `false` — so **registration is disabled unless the method is called**. Accepts a boolean or a closure evaluated with `$provider`, `$oauthUser`, and `$user` (the resolved user, or `null`).

### Methods
- `registration(Closure | bool $value = true): static`
- `getRegistration(): Closure | bool` (stored default: false)

### Parameters
- `$value` (Closure | bool) - Required - Boolean or closure.

### Return
- `registration`: static
- `getRegistration`: Closure | bool
```

--------------------------------

### Provider::color(string|array|null $color): static / getColor(): string|array|null

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/api-reference/provider.md

Sets or gets the button color. Accepts a named Filament color, a 50-950 hex palette array, or null. Default is Color::Gray.

```APIDOC
## Provider::color(string|array|null $color): static / getColor(): string|array|null

### Description
Sets the button color or retrieves the current color. Default is `Filament\Support\Colors\Color::Gray`.

### Method
Fluent setter / Getter

### Parameters (setter)
- **$color** (string|array{50: string, 100: string, 200: string, 300: string, 400: string, 500: string, 600: string, 700: string, 800: string, 900: string, 950: string}|null) - Required - The color value.

### Return Value (getter)
- **string|array|null** - The color value.

### Example
php
$provider->color('primary');
$color = $provider->getColor();

```

--------------------------------

### Catching InvalidCallbackPayload exception

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/errors.md

Example of catching the InvalidCallbackPayload exception when decrypting the panel from the OAuth callback. The previous exception is retrieved via getPrevious() and can be used to handle the invalid callback, e.g., abort(400) or redirect.

```php
use DutchCodingCompany\FilamentSocialite\Exceptions\InvalidCallbackPayload;

try {
    $panelId = PanelFromUrlQuery::decrypt($request);
} catch (InvalidCallbackPayload $e) {
    $previous = $e->getPrevious(); // Illuminate\Contracts\Encryption\DecryptException|null
    // Treat as invalid OAuth callback: abort(400) or redirect somewhere safe
}
```

--------------------------------

### Update panel configuration to include plugin

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/UPGRADE.md

Append the plugin to your panel provider's configuration and chain any desired options.

```php
->plugins([\DutchCodingCompany\FilamentSocialite\FilamentSocialitePlugin::make()])
```

--------------------------------

### Define OAuth callback route for Filament panel

Source: https://github.com/dutchcodingcompany/filament-socialite/blob/main/_autodocs/endpoints.md

Registers the OAuth callback route for a Filament panel. The route is public and CSRF-exempt, matching both GET and POST methods. It uses the panel's middleware plus the package's configured middleware, and names the route with the panel's route name for the callback.

```php
Route::domain($domain)
    ->match(['get', 'post'], "$slug/oauth/callback/{provider}", [SocialiteLoginController::class, 'processCallback'])
    ->middleware([
        ...$panel->getMiddleware(),
        ...config('filament-socialite.middleware'),
    ])
    ->name("socialite.{$panel->generateRouteName('oauth.callback')}");
```
Tokens:
Raw