Examples

Learn by studying these example plugins included with PteroCA.

hello-world Plugin

Location: plugins/hello-world/

Purpose: Demonstrates all plugin capabilities

Key Files to Study

• plugin.json - Complete manifest with all options

• Bootstrap.php - Initialization and cleanup

• src/Controller/HelloController.php - Routes and controllers

• src/Widget/HelloWidget.php - Dashboard widget

• src/EventSubscriber/MenuEventSubscriber.php - Menu customization

• src/Tab/ExampleTab.php - Server tab

• src/Command/GreetCommand.php - CLI command

• src/CronTask/ExampleTask.php - Scheduled task

• Migrations/Version.php* - Database setup

What It Demonstrates

• All 7 capabilities (routes, entities, migrations, ui, eda, console, cron)

• Service registration patterns

• Asset publishing

• Translations

• Event handling

• CRUD controller integration

Features Showcase

1. Dashboard Widget

Displays a simple greeting on the dashboard with configurable message.

// src/Widget/HelloWidget.php
class HelloWidget implements WidgetInterface
{
    public function getSupportedContexts(): array
    {
        return [WidgetContext::DASHBOARD];
    }

    public function getData(WidgetContext $context, array $contextData): array
    {
        $greeting = $this->pluginSettings->get('hello-world', 'greeting');
        return ['message' => $greeting ?? 'Hello, World!'];
    }
}

2. Custom Route

Simple controller that renders a page.

// src/Controller/HelloController.php
#[Route('/', name: 'index')]
public function index(): Response
{
    return $this->render('@PluginHelloWorld/index.html.twig', [
        'message' => 'Welcome to Hello World Plugin!'
    ]);
}

3. Console Command

CLI command to greet users.

php bin/console hello-world:greet John
# Output: Hello, John!

4. Cron Task

Example scheduled task.

// src/CronTask/ExampleTask.php
public function getSchedule(): string
{
    return '0 * * * *';  // Every hour
}

public function execute(): void
{
    $this->logger->info('Hello World cron task executed');
}

paypal-payment Plugin

Location: plugins/paypal-payment/

Purpose: Real-world payment provider integration

Key Files to Study

• src/Provider/PayPalPaymentProvider.php - Payment provider implementation

• src/Adapter/PayPalAdapter.php - SDK wrapper (adapter pattern)

• composer.json - External dependencies

• src/Controller/WebhookController.php - Webhook handling

What It Demonstrates

• Payment provider interface

• External SDK integration

• Adapter pattern for isolating external dependencies

• Webhook security and handling

• Settings management for API credentials

• Error handling and logging

Features Showcase

1. Payment Provider

Implementation of PaymentProviderInterface.

// src/Provider/PayPalPaymentProvider.php
public function createSession(
    string $userId,
    float $amount,
    string $currency,
    array $metadata = []
): ?PaymentSessionDTO {
    $session = $this->adapter->createPayment($amount, $currency);

    return new PaymentSessionDTO(
        id: $session['id'],
        status: $session['status'],
        amount: $amount,
        currency: $currency,
        checkoutUrl: $session['approval_url'],
        metadata: $metadata
    );
}

2. Adapter Pattern

Wraps PayPal SDK to isolate external dependency.

// src/Adapter/PayPalAdapter.php
class PayPalAdapter
{
    private ApiContext $apiContext;

    public function __construct(PluginSettingService $settings)
    {
        $clientId = $settings->get('paypal-payment', 'client_id');
        $secret = $settings->get('paypal-payment', 'client_secret');

        $this->apiContext = new ApiContext(
            new OAuthTokenCredential($clientId, $secret)
        );
    }

    public function createPayment(float $amount, string $currency): array
    {
        $payment = new Payment();
        // Configure payment...
        $payment->create($this->apiContext);

        return [
            'id' => $payment->getId(),
            'status' => $this->mapStatus($payment->getState()),
            'approval_url' => $payment->getApprovalLink()
        ];
    }
}

3. Webhook Handling

Secure webhook endpoint.

// src/Controller/WebhookController.php
#[Route('/webhook', name: 'webhook', methods: ['POST'])]
public function webhook(Request $request): Response
{
    // Verify webhook signature
    if (!$this->verifyWebhook($request)) {
        return new Response('Invalid signature', 400);
    }

    $event = json_decode($request->getContent(), true);

    match ($event['event_type']) {
        'PAYMENT.SALE.COMPLETED' => $this->handlePaymentCompleted($event),
        'PAYMENT.SALE.REFUNDED' => $this->handlePaymentRefunded($event),
        default => null
    };

    return new Response('OK', 200);
}

Creating Your Own Example

Minimal Plugin Structure

plugins/my-example/
├── plugin.json
├── Bootstrap.php
├── src/
│   └── Controller/
│       └── ExampleController.php
└── templates/
    └── index.html.twig

Minimal plugin.json

{
    "name": "my-example",
    "display_name": "My Example Plugin",
    "version": "1.0.0",
    "author": "Your Name",
    "description": "A minimal example plugin",
    "pteroca": {
        "min": "0.6.0"
    },
    "capabilities": ["routes", "ui"]
}

Minimal Controller

<?php
namespace Plugins\MyExample\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(name: 'plugin_my_example_')]
class ExampleController extends AbstractController
{
    #[Route('/', name: 'index')]
    public function index(): Response
    {
        return $this->render('@PluginMyExample/index.html.twig');
    }
}

Minimal Template

{# templates/index.html.twig #}
{% extends '@Core/base.html.twig' %}

{% block content %}
    <div class="container">
        <h1>My Example Plugin</h1>
        <p>This is a minimal example plugin.</p>
    </div>
{% endblock %}

Learning Path

1. Start with hello-world

Study the complete example to understand all capabilities.

2. Create a Simple Plugin

Build a basic plugin with just routes and templates.

3. Add Database

Add entities and migrations.

4. Implement Widgets

Create dashboard widgets.

5. Add Cron Tasks

Implement scheduled automation.

6. Study paypal-payment

Learn payment provider integration if needed.

7. Build Your Plugin

Apply everything you've learned to your own plugin idea.

Common Plugin Ideas

Analytics Plugin

Track and display statistics:

• Page views

• User activity

• Server usage

• Custom metrics

Capabilities needed: routes, entities, migrations, ui, cron

Backup Plugin

Automated backups:

• Database backups

• File backups

• Cloud storage integration

• Scheduled backups

Capabilities needed: console, cron, entities

Discord Integration

Sync with Discord:

• User role sync

• Notifications

• Commands via webhook

• Server status display

Capabilities needed: routes, entities, cron

Referral System

Reward user referrals:

• Referral tracking

• Bonus credits

• Leaderboard

• Statistics

Capabilities needed: routes, entities, migrations, ui, eda

Ticket System

Support ticket management:

• Create/manage tickets

• Email notifications

• Status tracking

• Admin interface

Capabilities needed: routes, entities, migrations, ui, eda

Getting Help

Resources

• Official Docs: https://docs.pteroca.com/for-developers/

• Discord: https://discord.com/invite/Gz5phhuZym

• GitHub: https://github.com/PteroCA-Org/panel

Community Examples

Check GitHub for community-created plugins:

• Search for "pteroca-plugin" topic

• Study popular plugins

• Ask in Discord for recommendations

Related Guides

• Getting Started - Plugin basics

• Plugin Structure - File organization

• Best Practices - Guidelines

• Testing - Ensure quality