OwnPay Plugin System: Architecture Overview

modules/
├── gateways/
│   └── stripe/
│       ├── manifest.json       # Plugin metadata and capabilities
│       ├── StripeGateway.php   # Entrypoint class
│       ├── icon.svg            # Gateway logo shown in admin
│       ├── assets/
│       │   └── checkout.js     # JS loaded on checkout page
│       └── migrations/
│           └── 001_create_stripe_logs.sql
├── addons/
│   └── email-logger/
│       ├── manifest.json
│       ├── Plugin.php
│       ├── Service/
│       │   └── Logger.php
│       ├── Cron/
│       │   └── CleanupJob.php
│       └── migrations/
│           └── 001_create_email_logs.sql
└── themes/
    └── my-theme/
        ├── manifest.json
        ├── Theme.php
        └── templates/
            ├── checkout.twig
            └── checkout-status.twig

{
  "name": "Stripe Payment Gateway",
  "slug": "stripe",
  "version": "1.0.0",
  "description": "Accept payments via Stripe — cards, wallets, international payments.",
  "author": "OwnPay Core",
  "type": "gateway",
  "entrypoint": "StripeGateway.php",
  "namespace": "OwnPay\\Modules\\Gateways\\Stripe",
  "capabilities": ["gateway"],
  "requires": {
    "core": ">=0.1.0",
    "php": ">=8.1"
  },
  "permissions": [
    "gateway.process",
    "gateway.refund"
  ]
}

<?php
declare(strict_types=1);

namespace OwnPay\Plugins\MyPlugin;

use OwnPay\Container;
use OwnPay\Event\EventManager;
use OwnPay\Plugin\Capability;
use OwnPay\Plugin\PluginInterface;

final class MyPlugin implements PluginInterface
{
    public static function metadata(): array
    {
        return [
            'name'        => 'My Plugin',
            'slug'        => 'my-plugin',
            'version'     => '1.0.0',
            'description' => 'A brief description of what this plugin does.',
            'author'      => 'Your Name',
            'type'        => 'addon',
        ];
    }

    public function capabilities(): array
    {
        return [Capability::ADDON, Capability::HOOKS];
    }

    public function register(EventManager $events, Container $container): void
    {
        // Register ALL hooks and filters here.
        // This is called during the boot phase, before boot().
        $events->addAction('payment.transaction.completed', [$this, 'onPaymentCompleted']);
    }

    public function boot(Container $container): void
    {
        // All DI services are fully resolved here.
        // Capture container services you need at request time.
    }

    public function deactivate(Container $container): void
    {
        // Flush caches, cancel remote subscriptions.
        // Do NOT drop tables here.
    }

    public function uninstall(Container $container): void
    {
        // Drop any op_plugin_* tables created by migrations.
        // Remove stored settings specific to this plugin.
    }

    public function fields(): array
    {
        // Configuration fields rendered in the plugin settings form.
        return [
            ['name' => 'api_key', 'label' => 'API Key', 'type' => 'password'],
        ];
    }
}

public function boot(Container $container): void
{
    // Resolve the settings repository
    $settings = $container->get(\OwnPay\Repository\SettingsRepository::class);

    // Read plugin-scoped settings (stored under group "plugin.{slug}")
    $apiKey = $settings->getGroup('plugin.my-plugin')['api_key'] ?? '';

    // Read brand-scoped settings for a specific merchant
    $brandSettings = $settings->forTenant($merchantId)->getGroup('plugin.my-plugin');
}

use OwnPay\Database\Database;

// Query builder — safe and recommended
$records = Database::table('op_plugin_my_plugin_logs')
    ->where('merchant_id', $merchantId)
    ->where('status', 'pending')
    ->get();

// Raw query with bound parameters — use named placeholders
$rows = Database::fetchAll(
    'SELECT * FROM op_plugin_my_plugin_logs WHERE trx_id = :trx_id',
    ['trx_id' => $trxId]
);

// Insert a row
Database::execute(
    'INSERT INTO op_plugin_my_plugin_logs (merchant_id, trx_id, created_at) VALUES (:mid, :trx, NOW())',
    ['mid' => $merchantId, 'trx' => $trxId]
);

"routes": [
    ["GET",  "/plugins/my-plugin/ping",  "ping"],
    ["POST", "/plugins/my-plugin/action","handleAction"],
    ["GET",  "/admin/my-plugin",         "adminHome", "admin"]
]

use OwnPay\Http\Request;
use OwnPay\Http\Response;

public function ping(Request $req): Response
{
    return Response::json(['ok' => true]);
}

public function adminHome(Request $req): Response
{
    return Response::html('<h1>My Plugin Admin</h1>');
}

"admin_menu": [
    { "label": "My Plugin", "url": "/admin/my-plugin" }
]

$events->addAction('admin.menu.register', function (): void {
    echo '<a href="/admin/my-plugin/reports" class="op-nav-link"><span>Reports</span></a>';
});

-- migrations/001_create_my_plugin_logs.sql
CREATE TABLE IF NOT EXISTS op_plugin_my_plugin_logs (
    id          BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    merchant_id INT UNSIGNED    NOT NULL,
    trx_id      VARCHAR(128)    NOT NULL,
    payload     JSON            DEFAULT NULL,
    created_at  DATETIME(6)     NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
    INDEX idx_merchant_trx (merchant_id, trx_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;