# Pelican Panel Plugins

> Write, scaffold, explain, and debug plugins for the Pelican gaming panel. Use this skill whenever the user mentions Pelican plugins, extending Pelican, FilamentPHP resources or pages for Pelican, plugin service providers, custom permissions, plugin settings, routes, models, widgets, or asks how to add new functionality to the Pelican panel.

- Skill: `aaronflorey/pelican-panel-plugins` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add aaronflorey/pelican-panel-plugins`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aaronflorey/pelican-panel-plugins/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: aaronflorey (https://skillmd.com/u/aaronflorey)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aaronflorey/pelican-panel-plugins

---


# Pelican Panel Plugins

Pelican is an open-source game server management panel built on Laravel + FilamentPHP. Plugins let you add functionality without touching core files.

> ⚠️ The plugin system is still in active development — some features may change.

## Quick Reference

📖 **Detailed Guides:**
- [FilamentPHP Patterns](references/filament-patterns.md) - Resources, pages, widgets, actions, relation managers
- [Advanced Patterns](references/advanced-patterns.md) - Models, services, routes, commands, events
- [Complete Plugin Walkthrough](examples/complete-plugin-walkthrough.md) - Step-by-step example

## Scaffolding a New Plugin

Run inside the panel directory (`/var/www/pelican` by default):

```bash
php artisan p:plugin:make
```

This creates the basic structure with `plugin.json`, main plugin class, service provider, and config file.

> **Critical:** The plugin folder name must exactly match the `id` field in `plugin.json`.

## Plugin Structure

```
plugins/my-plugin/
├── plugin.json              # Metadata and configuration
├── config/
│   └── my-plugin.php       # Config values (use env vars)
├── database/
│   └── migrations/         # Auto-discovered migrations
├── lang/                   # Translations (namespaced: my-plugin::strings.key)
├── resources/
│   └── views/              # Blade views (namespaced: my-plugin::view-name)
├── routes/                 # Optional route files
└── src/                    # App logic (PSR-4 autoloaded)
    ├── MyPlugin.php        # Main plugin class
    ├── Filament/
    │   ├── Admin/          # Admin panel components
    │   │   ├── Pages/
    │   │   ├── Resources/
    │   │   └── Widgets/
    │   ├── App/            # Server list panel
    │   └── Server/         # Server management panel
    ├── Models/
    ├── Policies/           # Auto-discovered
    ├── Providers/          # Auto-discovered service providers
    ├── Console/Commands/   # Auto-discovered artisan commands
    └── Http/
        └── Controllers/
```

Everything in standard Laravel locations is **auto-discovered**: migrations, providers, commands, policies.

## plugin.json

```json
{
    "id": "my-plugin",
    "name": "My Plugin",
    "author": "Your Name",
    "version": "1.0.0",
    "description": "Short description",
    "category": "plugin",
    "namespace": "MyName\\MyPlugin",
    "class": "MyPlugin",
    "panels": ["admin", "server"],
    "panel_version": "^1.2.0",
    "composer_packages": {
        "vendor/package": "^1.0"
    }
}
```

| Field | Required | Notes |
|---|---|---|
| `id` | ✅ | Must match folder name |
| `namespace` | ✅ | PHP namespace root (use `\\` for backslashes) |
| `class` | ✅ | Main class name (in `src/`) |
| `category` | ✅ | `plugin`, `theme`, or `language` |
| `panels` | No | Array of panel IDs or omit for all panels |
| `panel_version` | No | Minimum panel version (e.g., `^1.2.0`) |
| `composer_packages` | No | External dependencies |

## Main Plugin Class

Located in `src/{ClassName}.php`:

```php
namespace MyName\MyPlugin;

use Filament\Contracts\Plugin;
use Filament\Panel;

class MyPlugin implements Plugin
{
    public function getId(): string
    {
        return 'my-plugin';
    }

    public function register(Panel $panel): void
    {
        $id = str($panel->getId())->title(); // "Admin", "App", "Server"

        // Auto-discover Filament components
        $panel->discoverPages(
            plugin_path($this->getId(), "src/Filament/$id/Pages"),
            "MyName\\MyPlugin\\Filament\\$id\\Pages"
        );
        $panel->discoverResources(
            plugin_path($this->getId(), "src/Filament/$id/Resources"),
            "MyName\\MyPlugin\\Filament\\$id\\Resources"
        );
        $panel->discoverWidgets(
            plugin_path($this->getId(), "src/Filament/$id/Widgets"),
            "MyName\\MyPlugin\\Filament\\$id\\Widgets"
        );
    }

    public function boot(Panel $panel): void
    {
        //
    }
}
```

## The Three Filament Panels

| Panel ID | Area | Use Case |
|---|---|---|
| `admin` | Admin area | Full CRUD for resources, settings, management |
| `app` | Server list | Minimal UI (no nav by default) |
| `server` | Server management | Tenant-scoped (current server context) |

### Enabling Navigation on `app` Panel

```php
use App\Filament\App\Resources\Servers\ServerResource;
use App\Enums\CustomizationKey;

public function register(Panel $panel): void
{
    parent::register($panel);

    if ($panel->getId() === 'app') {
        ServerResource::embedServerList();
        $panel->navigation(true);
        $panel->topbar(function () {
            $nav = user()?->getCustomization(CustomizationKey::TopNavigation);
            return in_array($nav, ['topbar', 'mixed', true], true);
        });
        $panel->clearCachedComponents();
    }
}
```

## Extending Core Resources

Call static methods on core classes inside a **service provider's `register()`**:

```php
use App\Filament\Admin\Resources\Users\UserResource;
use App\Filament\Admin\Resources\Servers\ServerResource;
use App\Models\Role;

public function register(): void
{
    // Add a relation manager tab
    ServerResource::registerCustomRelations(MyRelationManager::class);
    
    // Register permissions
    Role::registerCustomDefaultPermissions('myModel');
    Role::registerCustomModelIcon('myModel', 'tabler-star');
}
```

**Available customization traits** (check `app/Traits/Filament/` for all):
- `CanModifyResource` - Relation managers, custom actions
- `CanCustomizePage` - Widgets, header actions
- `CanModifyForm` / `CanModifyTable` - Form/table hooks

## Plugin Settings

Implement `HasPluginSettings` on your main class:

```php
use App\Contracts\Plugins\HasPluginSettings;
use App\Traits\EnvironmentWriterTrait;
use Filament\Forms\Components\TextInput;
use Filament\Notifications\Notification;

class MyPlugin implements Plugin, HasPluginSettings
{
    use EnvironmentWriterTrait;

    public function getSettingsForm(): array
    {
        return [
            TextInput::make('api_key')
                ->required()
                ->default(fn () => config('my-plugin.api_key')),
        ];
    }

    public function saveSettings(array $data): void
    {
        $this->writeToEnvironment([
            'MY_PLUGIN_API_KEY' => $data['api_key'],
        ]);

        Notification::make()->title('Settings saved')->success()->send();
    }
}
```

> Always prefix env vars with your plugin ID to avoid conflicts.

## Permissions

### Admin Role Permissions

In your service provider's `register()`:

```php
use App\Models\Role;

// Shorthand: registers viewList, view, create, update, delete
Role::registerCustomDefaultPermissions('myModel');

// Custom permissions
Role::registerCustomPermissions([
    'myModel' => ['export', 'approve'],
    'server'  => ['customAction'], // extend existing model
]);

// Optional: icon for permission group
Role::registerCustomModelIcon('myModel', 'tabler-star');
```

### Subuser Permissions

```php
use App\Models\Subuser;

// New permission group
Subuser::registerCustomPermissions('myFeature', ['read', 'write'], 'tabler-bolt', false);

// Append to existing group
Subuser::registerCustomPermissions('console', ['myCustomAction']);
```

## Routes

Create a `RouteServiceProvider` in `src/Providers/`:

```php
use Illuminate\Foundation\Support\Providers\RouteServiceProvider;
use Illuminate\Support\Facades\Route;

class MyPluginRoutesProvider extends RouteServiceProvider
{
    public function boot(): void
    {
        $this->routes(function () {
            // Simple route
            Route::get('/my-plugin/test', [TestController::class, 'index'])
                ->name('my-plugin.test');

            // Load from file
            Route::prefix('/my-plugin')
                ->group(plugin_path('my-plugin', 'routes/web.php'));

            // Append to client API
            Route::middleware(['api', 'client-api', 'throttle:api.client'])
                ->prefix('/api/client/servers/{server}')
                ->scopeBindings()
                ->group(plugin_path('my-plugin', 'routes/api-client.php'));
        });
    }
}
```

## Models & Relationships

### Add Relationship to Core Models

In your service provider's `boot()`:

```php
use App\Models\Server;
use MyPlugin\Models\Ticket;

public function boot(): void
{
    Server::resolveRelationUsing('tickets', fn (Server $server) => 
        $server->hasMany(Ticket::class, 'server_id', 'id')
    );
}
```

Now `$server->tickets` works everywhere.

### Policies

```php
use App\Policies\DefaultAdminPolicies;

class MyModelPolicy
{
    use DefaultAdminPolicies;
    
    protected string $modelName = 'myModel';
}
```

This automatically checks admin role permissions based on the registered model name.

## Translations

Place in `lang/{locale}/` (e.g., `lang/en/strings.php`):

```php
return [
    'welcome' => 'Welcome',
    'item' => 'Item|Items', // Pluralization
];
```

Usage:
```php
trans('my-plugin::strings.welcome')
trans_choice('my-plugin::strings.item', 2) // "Items"
```

## Views

Place in `resources/views/`:

```php
view('my-plugin::my-view')
// → plugins/my-plugin/resources/views/my-view.blade.php
```

## Common Patterns

### FilamentPHP Components

See [FilamentPHP Patterns](references/filament-patterns.md) for:
- Resources (CRUD interfaces)
- Pages (custom pages)
- Widgets (dashboard components)
- Relation Managers (manage related records)
- Custom Actions (reusable buttons)
- Form components (inputs, selects, toggles)
- Table columns and filters

### Advanced Patterns

See [Advanced Patterns](references/advanced-patterns.md) for:
- Model events and hooks
- Enums with Filament interfaces
- Service classes
- HTTP controllers and API routes
- Artisan commands and scheduling
- HTTP macros for external APIs
- Database migrations
- Error handling

### Complete Example

See [Complete Plugin Walkthrough](examples/complete-plugin-walkthrough.md) for a step-by-step guide building a "Server Notes" plugin.

## Publishing a Plugin

1. Open `plugin.json` and **remove** the `meta` block (internal use only)
2. Zip the entire plugin folder
3. Share the zip — users install via panel UI Import button or manually drop into `plugins/`

Publish to the community:
- GitHub: [pelican-dev/plugins](https://github.com/pelican-dev/plugins)
- Discord: `#plugins` channel at [discord.gg/pelican-panel](https://discord.gg/pelican-panel)

## Tips & Gotchas

- **Namespace in plugin.json**: Use `\\` (double backslash) for namespace separators
- **Migration naming**: Use numeric prefixes (`001_`, `002_`) to control execution order
- **Environment variables**: Always prefix with your plugin ID (e.g., `MY_PLUGIN_*`)
- **Panel context**: Use `Filament::getTenant()` to get current server in server panel
- **Auto-discovery**: Service providers, commands, migrations, and policies are auto-discovered
- **Relation managers**: Must be registered on core resources via `registerCustomRelations()` in service provider's `register()` method
- **Testing**: Use `php artisan migrate:fresh --seed` to reset and test migrations
- **Permissions**: Register in service provider's `register()`, not `boot()`

## Getting Help

- **Documentation**: [pelican.dev/docs/panel](https://pelican.dev/docs/panel)
- **Discord**: [discord.gg/pelican-panel](https://discord.gg/pelican-panel)
- **GitHub**: [github.com/pelican-dev/panel](https://github.com/pelican-dev/panel)
- **Example Plugins**: [github.com/pelican-dev/plugins](https://github.com/pelican-dev/plugins)