Build plugins for Panelr.

What is a plugin?

A Panelr plugin is a PHP class that connects a Panelr installation to an IPTV panel's API. Every IPTV provider uses a panel to manage their streams and subscribers: XtreamUI, custom panels, proprietary systems. Panelr is panel-agnostic by design. Instead of building native support for every panel that exists, Panelr uses plugins to bridge that gap.

When a provider installs your plugin, Panelr can create lines, renew subscriptions, sync products, update bouquets and manage subscribers automatically, all through your panel's API.

How it works

Build your integration around the panel API and the plugin interface:

1. Create a PHP class implementing PanelPluginInterface.
2. Implement the panel API calls and declare the capabilities your panel supports.
3. Test your plugin's configuration, connection, and supported actions against your panel.

Getting started

Plugin skeleton

Create a new PHP file named after your class, for example MyPanelPlugin.php. The filename must match the class name exactly.

<?php

class MyPanelPlugin implements PanelPluginInterface
{
    private array $config = [];

    public function getName(): string
    {
        return 'My Panel Plugin';
    }

    public function getVersion(): string
    {
        return '1.0.0';
    }

    public function getCapabilities(): array
    {
        return ['products', 'activations', 'bouquets'];
    }

    public function getRequiredConfigFields(): array
    {
        return [
            [
                'key'         => 'api_url',
                'label'       => 'Panel API URL',
                'type'        => 'url',
                'required'    => true,
                'default'     => '',
                'description' => 'Base URL of your panel API',
            ],
            [
                'key'         => 'api_key',
                'label'       => 'API Key',
                'type'        => 'password',
                'required'    => true,
                'default'     => '',
                'description' => 'Your panel API key',
            ],
        ];
    }

    public function configure(array $config): void
    {
        $this->config = $config;
    }

    public function testConnection(): array
    {
        $ch = curl_init($this->config['api_url'] . '/ping');
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER     => ['X-Api-Key: ' . $this->config['api_key']],
            CURLOPT_TIMEOUT        => 10,
        ]);
        $response = curl_exec($ch);
        $code     = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        return $code === 200
            ? ['success' => true,  'message' => 'Connected successfully.']
            : ['success' => false, 'message' => 'Could not connect to panel.'];
    }

    // Implement remaining interface methods...
}

Plugin structure

Your plugin is a PHP class implementing PanelPluginInterface. Name the file to match the class, for example MyPanelPlugin.php.

Naming rules

• Your PHP filename must match your class name exactly: MyPanelPlugin.php → class MyPanelPlugin
• Class names must be unique across installed plugins
• One class per file

Interface reference

Every plugin must implement all methods of PanelPluginInterface. Every method returns an array containing at minimum a success key. Methods gated behind a capability are only called when that capability is declared in getCapabilities(), but all methods must still be present in your class.

Identity

Configuration

Connection

['success' => true,  'message' => 'Connected successfully.']
['success' => false, 'message' => 'Could not connect to panel.']

Activations

['success' => true, 'data' => [
    'panel_user_id'   => '1234',
    'xtream_username' => 'abc123',
    'xtream_password' => 'xyz789',
    'expiration_date' => '2027-01-01 00:00:00',
    'xtream_host'     => 'http://panel.example.com:8080', // optional
    'm3u_url'         => 'http://...',                    // optional
]]

['success' => true, 'data' => [
    'expiration_date' => '2028-01-01 00:00:00',
]]

Products

Bouquets

Other

Adding connections to a running line (optional)

A panel that can move a running line to a package with more connections for the rest of its term declares the connection_upgrade capability and adds these two methods. They are not declared in PanelPluginInterface, so a plugin without them keeps loading unchanged. Panelr calls them only on a plugin that declares the capability. Panelr prices the upgrade for the customer and moves the line to the new plan once the panel confirms. The line's expiry must not change.

['success' => true, 'data' => [
    'targets' => [
        [
            'product_id'  => '14',        // your package ID, as syncProducts() reports it
            'connections' => 3,
            'charge'      => '3.000000',  // what the panel charges the reseller today, or null
        ],
    ],
    'unavailable_reason' => '',           // why targets is empty
]]

// Success
['success' => true, 'data' => [
    'connections'     => 3,
    'charged'         => '3.000000',           // what the reseller was charged
    'expiration_date' => '2027-04-12 10:00:00', // unchanged
]]

// The charge rose since the order was quoted — nothing charged
['success' => false, 'price_changed' => true, 'message' => 'The upgrade now costs more than it was quoted.']

// Any other refusal — Panelr keeps the order open for the admin
['success' => false, 'message' => 'The reseller balance does not cover this upgrade.']

Capabilities

Declare only the capabilities your panel actually supports. Panelr uses them to show or hide admin controls. Undeclared capabilities are never displayed.

Security rules

Follow these rules when writing your plugin.

Allowed

• curl_* functions for HTTP requests to your panel API
• json_encode, json_decode, urlencode, urldecode
• date, time, strtotime, date_create
• All standard string, array, and math functions

Blocked

• System execution: exec, shell_exec, system, passthru, proc_open
• Code evaluation: eval, assert, create_function
• File system access: fopen, fwrite, file_put_contents, file_get_contents
• Database access: mysqli_*, new PDO
• File includes: include, require
• Superglobals: $_GET, $_POST, $_SERVER, $_SESSION
• Output: echo, print, var_dump
• Obfuscation: base64_decode+eval chains, variable variables