From 0e9544822d9537458654979b403517f939a79b04 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Sun, 4 Jan 2026 13:20:32 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`main`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @Ebnater.

* https://github.com/pelican-dev/plugins/pull/75#issuecomment-3708082066

The following files were modified:

* `pocketid-provider/src/Extensions/OAuth/Schemas/PocketIDSchema.php`
* `pocketid-provider/src/PocketIDProviderPlugin.php`
* `pocketid-provider/src/Providers/PocketIDProviderPluginProvider.php`
---
 .../OAuth/Schemas/PocketIDSchema.php          | 143 ++++++++++++++++++
 .../src/PocketIDProviderPlugin.php            |  41 +++++
 .../PocketIDProviderPluginProvider.php        |  21 +++
 3 files changed, 205 insertions(+)
 create mode 100644 pocketid-provider/src/Extensions/OAuth/Schemas/PocketIDSchema.php
 create mode 100644 pocketid-provider/src/PocketIDProviderPlugin.php
 create mode 100644 pocketid-provider/src/Providers/PocketIDProviderPluginProvider.php

diff --git a/pocketid-provider/src/Extensions/OAuth/Schemas/PocketIDSchema.php b/pocketid-provider/src/Extensions/OAuth/Schemas/PocketIDSchema.php
new file mode 100644
index 0000000..13da881
--- /dev/null
+++ b/pocketid-provider/src/Extensions/OAuth/Schemas/PocketIDSchema.php
@@ -0,0 +1,143 @@
+<?php
+
+namespace Ebnater\PocketIDProvider\Extensions\OAuth\Schemas;
+
+use App\Extensions\OAuth\Schemas\OAuthSchema;
+use Filament\Forms\Components\ColorPicker;
+use Filament\Forms\Components\TextInput;
+use Filament\Infolists\Components\TextEntry;
+use Filament\Schemas\Components\Wizard\Step;
+use Illuminate\Support\Facades\Blade;
+use Illuminate\Support\HtmlString;
+use SocialiteProviders\PocketID\Provider;
+
+final class PocketIDSchema extends OAuthSchema
+{
+    /**
+     * Returns the identifier for the Pocket ID OAuth provider schema.
+     *
+     * @return string The provider identifier "pocketid".
+     */
+    public function getId(): string
+    {
+        return 'pocketid';
+    }
+
+    /**
+     * Get the Socialite provider class used for Pocket ID.
+     *
+     * @return string The fully-qualified Socialite provider class name for Pocket ID.
+     */
+    public function getSocialiteProvider(): string
+    {
+        return Provider::class;
+    }
+
+    /**
+     * Provide the service configuration array for the Pocket ID OAuth provider.
+     *
+     * @return array The service configuration array. Includes a 'base_url' entry sourced from the `OAUTH_POCKETID_BASE_URL` environment variable.
+     */
+    public function getServiceConfig(): array
+    {
+        return array_merge(parent::getServiceConfig(), [
+            'base_url' => env('OAUTH_POCKETID_BASE_URL'),
+        ]);
+    }
+
+    /**
+     * Provide setup steps required to configure Pocket ID as an OAuth provider.
+     *
+     * Returns an array of setup Step instances that guide the user through configuring a Pocket ID application;
+     * the steps include rendered HTML instructions and a disabled TextInput showing the required callback URL.
+     *
+     * @return array An array of Step objects for the setup UI, including an instructional HTML entry and a read-only callback URL field.
+     */
+    public function getSetupSteps(): array
+    {
+        return array_merge([
+            Step::make('Configure Pocket ID Application')
+                ->schema([
+                    TextEntry::make('instructions')
+                        ->hiddenLabel()
+                        ->state(new HtmlString(Blade::render('
+                            <ol class="list-decimal list-inside space-y-1">
+                                <li>Log in to your Pocket ID instance</li>
+                                <li>Navigate to your application or create a new OAuth application</li>
+                                <li>Copy the <strong>Client ID</strong> and <strong>Client Secret</strong> from your Pocket ID application</li>
+                                <li>Configure the redirect URL shown below in your Pocket ID application settings</li>
+                            </ol>
+                        '))),
+                    TextInput::make('_noenv_callback')
+                        ->label('Callback URL')
+                        ->dehydrated()
+                        ->disabled()
+                        ->default(fn () => url('/auth/oauth/callback/pocketid')),
+                ]),
+        ], parent::getSetupSteps());
+    }
+
+    /**
+     * Builds the settings form fields for the Pocket ID OAuth provider.
+     *
+     * Returns the provider-specific settings merged with the parent form and includes:
+     * - `OAUTH_POCKETID_BASE_URL`: base URL for the Pocket ID service (URL-validated).
+     * - `OAUTH_POCKETID_DISPLAY_NAME`: user-facing display name for the provider.
+     * - `OAUTH_POCKETID_DISPLAY_COLOR`: hex color used for provider display.
+     *
+     * @return array An array of form field definitions for the settings form.
+     */
+    public function getSettingsForm(): array
+    {
+        return array_merge(parent::getSettingsForm(), [
+            TextInput::make('OAUTH_POCKETID_BASE_URL')
+                ->label('Base URL')
+                ->placeholder('https://id.example.com')
+                ->columnSpan(2)
+                ->required()
+                ->url()
+                ->autocomplete(false)
+                ->default(env('OAUTH_POCKETID_BASE_URL')),
+            TextInput::make('OAUTH_POCKETID_DISPLAY_NAME')
+                ->label('Display Name')
+                ->placeholder('Pocket ID')
+                ->autocomplete(false)
+                ->default(env('OAUTH_POCKETID_DISPLAY_NAME', 'Pocket ID')),
+            ColorPicker::make('OAUTH_POCKETID_DISPLAY_COLOR')
+                ->label('Display Color')
+                ->placeholder('#000000')
+                ->default(env('OAUTH_POCKETID_DISPLAY_COLOR', '#000000'))
+                ->hex(),
+        ]);
+    }
+
+    /**
+     * Get the display name for the Pocket ID provider.
+     *
+     * @return string The display name from the `OAUTH_POCKETID_DISPLAY_NAME` environment variable, or `'Pocket ID'` if not set.
+     */
+    public function getName(): string
+    {
+        return env('OAUTH_POCKETID_DISPLAY_NAME', 'Pocket ID');
+    }
+
+    /**
+     * Gets the UI icon identifier for the provider.
+     *
+     * @return string The icon identifier used to represent the provider (e.g., 'heroicon-o-identification').
+     */
+    public function getIcon(): string
+    {
+        return 'heroicon-o-identification';
+    }
+
+    /**
+     * Get the provider's display color as a hex string.
+     *
+     * @return string The hex color used for the provider's display (e.g., '#000000'); defaults to '#000000' if not configured.
+     */
+    public function getHexColor(): string
+    {
+        return env('OAUTH_POCKETID_DISPLAY_COLOR', '#000000');
+    }
+}
\ No newline at end of file
diff --git a/pocketid-provider/src/PocketIDProviderPlugin.php b/pocketid-provider/src/PocketIDProviderPlugin.php
new file mode 100644
index 0000000..7941284
--- /dev/null
+++ b/pocketid-provider/src/PocketIDProviderPlugin.php
@@ -0,0 +1,41 @@
+<?php
+
+namespace Ebnater\PocketIDProvider;
+
+use Filament\Contracts\Plugin;
+use Filament\Panel;
+
+class PocketIDProviderPlugin implements Plugin
+{
+    /**
+     * Get the plugin's unique identifier.
+     *
+     * @return string The plugin identifier "pocketid-provider".
+     */
+    public function getId(): string
+    {
+        return 'pocketid-provider';
+    }
+
+    /**
+     * Registers Filament resources for the given panel by discovering them under the plugin's Filament resources path.
+     *
+     * Discovers resources located in "src/Filament/<TitleCasedPanelId>/Resources" inside this plugin and maps them to the
+     * PHP namespace "Ebnater\\PocketIDProvider\\Filament\\<TitleCasedPanelId>\\Resources".
+     *
+     * @param \Filament\Panel $panel The Filament panel whose resources should be discovered and registered.
+     */
+    public function register(Panel $panel): void
+    {
+        $id = str($panel->getId())->title();
+
+        $panel->discoverResources(plugin_path($this->getId(), "src/Filament/$id/Resources"), "Ebnater\\PocketIDProvider\\Filament\\$id\\Resources");
+    }
+
+    /**
+ * Execute boot-time initialization for the given Filament panel.
+ *
+ * @param Panel $panel The Filament panel instance the plugin is booting for.
+ */
+public function boot(Panel $panel): void {}
+}
\ No newline at end of file
diff --git a/pocketid-provider/src/Providers/PocketIDProviderPluginProvider.php b/pocketid-provider/src/Providers/PocketIDProviderPluginProvider.php
new file mode 100644
index 0000000..9bf5aa8
--- /dev/null
+++ b/pocketid-provider/src/Providers/PocketIDProviderPluginProvider.php
@@ -0,0 +1,21 @@
+<?php
+
+namespace Ebnater\PocketIDProvider\Providers;
+
+use App\Extensions\OAuth\OAuthService;
+use Ebnater\PocketIDProvider\Extensions\OAuth\Schemas\PocketIDSchema;
+use Illuminate\Support\ServiceProvider;
+
+class PocketIDProviderPluginProvider extends ServiceProvider
+{
+    /**
+     * Register the PocketID OAuth schema with the application's OAuthService.
+     *
+     * Resolves the OAuthService from the service container and registers a new PocketIDSchema instance.
+     */
+    public function boot(): void
+    {
+        $service = $this->app->make(OAuthService::class);
+        $service->register(new PocketIDSchema());
+    }
+}
\ No newline at end of file