Парсер курсов

Плагин курсов — это внешний модуль iEXExchanger, который добавляет в систему новый источник курсов.

После установки через раздел «Установка плагинов» такой модуль может создать группу в системе «Курсы из источников», загрузить валютные пары и использоваться в направлениях обмена как обычный источник курса.

Этот документ предназначен для разработчиков и описывает создание плагина курсов: структуру файлов, файл iex-plugin.json, PHP-класс парсера, настройки, секреты, пары, health-check, миграции и сборку ZIP-архива.

Общий принцип работы

Плагин не изменяет ядро iEXExchanger и не устанавливается в папку packages.

Он поставляется как отдельный ZIP-архив, проходит проверку через админку и сохраняется в системе внешних плагинов.

Общая схема работы:

1. Разработчик создаёт папку плагина.
2. Внутри добавляет файл iex-plugin.json.
3. Создаёт PHP-класс парсера.
4. PHP-класс получает курсы из API, файла или другого источника.
5. Плагин упаковывается в ZIP.
6. Администратор загружает ZIP через «Утилиты» — «Установка плагинов».
7. Система проверяет пакет.
8. После установки создаётся источник курсов.
9. Пары курсов импортируются в раздел источников.
10. Оператор включает нужные пары и использует их в направлениях обмена.

Основной стандарт плагина

Для плагинов курсов используется тип:

parser-rate

Основная возможность плагина:

rates.source

Стандарт совместимости:

iex.parser-rate.v1

Рекомендуемый runtime:

php

Runtime js сохранён только для совместимости со старыми parser-rate модулями. Для новых плагинов рекомендуется использовать PHP.

---

Быстрый старт

Для создания шаблона плагина используйте команду:

php artisan iex:plugin-make test-rates --type=parser-rate --runtime=php --title="Test Rates"

После выполнения будет создана папка:

storage/app/iex-plugin-templates/test-rates/

Структура шаблона:

test-rates/
├── iex-plugin.json
├── README.md
└── src/
    └── Parser.php

Чтобы сразу собрать ZIP-архив, используйте:

php artisan iex:plugin-make test-rates --type=parser-rate --runtime=php --title="Test Rates" --zip --force

Если нужно, чтобы плагин при установке попробовал получить пары из источника:

php artisan iex:plugin-make test-rates --type=parser-rate --runtime=php --title="Test Rates" --discover-on-install --zip --force

---

Структура плагина

Минимальная структура PHP-плагина курсов:

test-rates/
├── iex-plugin.json
└── src/
    └── Parser.php

Расширенная структура:

test-rates/
├── iex-plugin.json
├── icon.png
├── README.md
└── src/
    └── Parser.php

Иконка плагина

Иконку можно добавить в корень плагина.

Поддерживаемые имена:

icon.svg
icon.png
icon.webp
icon.jpg
icon.jpeg

Для SVG система выполняет дополнительную проверку безопасности. Нельзя использовать скрипты, активные события и внешние ссылки внутри SVG.

Примеры

5KB

rapira-rates.zip

archive

Открыть

6KB

rates-2328.zip

archive

Открыть

---

Файл iex-plugin.json

iex-plugin.json — главный файл описания плагина.

Через него система понимает:

• какой это тип плагина;
• как он называется;
• какая у него версия;
• какой runtime используется;
• с какими версиями iEXExchanger он совместим;
• какие настройки нужно показать в админке;
• какие секреты нужно запросить;
• какие пары курсов можно создать;
• какой PHP-класс нужно запустить.

Полный пример iex-plugin.json

{
  "type": "parser-rate",
  "runtime": "php",
  "standard": "iex.parser-rate.v1",
  "name": "example-rates",
  "title": "Example Rates",
  "description": "Источник курсов Example API.",
  "version": "1.0.0",
  "activeByDefault": false,
  "compatibility": {
    "core_min": "11.1.8",
    "core_max": null,
    "php": "^8.2|^8.3|^8.4",
    "extensions": ["json", "curl"]
  },
  "modules": [
    {
      "capability": "rates.source",
      "type": "parser-rate",
      "title": "Example Rates",
      "description": "Источник курсов Example API.",
      "standard": "iex.parser-rate.v1",
      "settings": [
        {
          "key": "api_key",
          "label": "API key",
          "type": "secret",
          "required": true
        }
      ],
      "config_schema": [
        {
          "key": "base_url",
          "label": "Base URL",
          "type": "url",
          "required": true,
          "default": "https://api.example.com"
        },
        {
          "key": "timeout",
          "label": "Timeout",
          "type": "integer",
          "required": false,
          "default": 10
        }
      ],
      "migrations": [],
      "health": {}
    }
  ],
  "rateParser": {
    "discoverOnInstall": true,
    "pairs": [
      {
        "from": "USD",
        "to": "RUB",
        "amount": "91.25",
        "number_format": 10,
        "status": false
      }
    ]
  }
}

---

Основные поля iex-plugin.json

1

type

Тип плагина.

Для парсера курсов всегда используется:

"type": "parser-rate"

2

runtime

Среда выполнения плагина.

Для новых плагинов рекомендуется:

"runtime": "php"

3

standard

Стандарт совместимости.

Для парсера курсов:

"standard": "iex.parser-rate.v1"

4

name

Системное имя плагина.

"name": "example-rates"

Требования:

• только латиница;
• можно использовать цифры;
• можно использовать - и _;
• нельзя использовать пробелы;
• нельзя использовать кириллицу;
• нельзя использовать /, \, ...

name используется как системный slug плагина и alias источника курсов.

5

title

Название плагина в админке.

"title": "Example Rates"

6

description

Краткое описание плагина.

"description": "Источник курсов Example API."

7

version

Версия плагина.

"version": "1.0.0"

8

activeByDefault

Определяет, будет ли плагин активен сразу после установки.

"activeByDefault": false

Рекомендуется оставлять false, чтобы администратор сначала проверил настройки и health-check.

---

Совместимость

Блок compatibility помогает системе заранее понять, подходит ли плагин для текущей версии продукта.

"compatibility": {
  "core_min": "11.1.8",
  "core_max": null,
  "php": "^8.2|^8.3|^8.4",
  "extensions": ["json", "curl"]
}

Поле	Назначение
core_min	Минимальная версия iEXExchanger
core_max	Максимальная версия iEXExchanger
php	Поддерживаемые версии PHP
extensions	Обязательные PHP-расширения

Если верхнее ограничение по версии продукта не требуется, используйте:

"core_max": null

entry и class

entry и class можно не указывать, если используется стандартная структура.

Для PHP-плагина курсов система по умолчанию ожидает файл:

src/Parser.php

И класс:

iEXPlugins\ExampleRates\Parser

Например, если указано:

"name": "example-rates"

ожидаемый PHP-класс:

namespace iEXPlugins\ExampleRates;

final class Parser

Когда entry и class нужно указывать

Если файл или класс называются нестандартно, укажите их явно:

"entry": "src/CustomParser.php",
"class": "iEXPlugins\\ExampleRates\\CustomParser"

Тогда в PHP-файле должен быть такой класс:

namespace iEXPlugins\ExampleRates;

final class CustomParser

Блок modules

modules описывает возможности плагина.

Для плагина курсов рекомендуется явно указывать:

rates.source

Пример:

"modules": [
  {
    "capability": "rates.source",
    "type": "parser-rate",
    "title": "Example Rates",
    "description": "Источник курсов Example API.",
    "standard": "iex.parser-rate.v1",
    "settings": [],
    "config_schema": [],
    "migrations": [],
    "health": {}
  }
]

Если modules не указан, система для parser-rate может создать rates.source по умолчанию. Но для новых плагинов лучше указывать modules явно, чтобы структура была понятной и предсказуемой.

PHP-класс Parser.php

Основной файл плагина:

src/Parser.php

Минимальный пример:

<?php

declare(strict_types=1);

namespace iEXPlugins\ExampleRates;

use iEXPackages\PluginManager\Contracts\RateParserPluginInterface;
use iEXPackages\PluginManager\DTO\RateParserContext;

final class Parser implements RateParserPluginInterface
{
    public function rates(RateParserContext $context): iterable
    {
        return [
            [
                'from' => 'USD',
                'to' => 'RUB',
                'buy' => '91.25',
            ],
            [
                'from' => 'EUR',
                'to' => 'RUB',
                'buy' => '98.10',
            ],
        ];
    }
}

Класс должен реализовать интерфейс:

RateParserPluginInterface

И содержать метод:

public function rates(RateParserContext $context): iterable

Если класс не реализует интерфейс, система не сможет запустить плагин.

Формат возвращаемого курса

Основной формат курса:

[
    'from' => 'USD',
    'to' => 'RUB',
    'buy' => '91.25',
]

Можно дополнительно вернуть sell:

[
    'from' => 'USD',
    'to' => 'RUB',
    'buy' => '91.25',
    'sell' => '91.80',
]

Значения курсов лучше возвращать строками, чтобы не терять точность на float.

Поддерживаемые alias-поля

Рекомендуемый формат:

from / to / buy / sell

Система также понимает alias-ключи:

Основное поле	Alias
from	base, currency_from, code_in
to	quote, currency_to, code_out
buy	rate, default, value, bid
sell	ask

Пример:

[
    'base' => 'USD',
    'quote' => 'RUB',
    'rate' => '91.25',
]

---

Пример парсера с HTTP API

<?php

declare(strict_types=1);

namespace iEXPlugins\ExampleRates;

use Illuminate\Support\Facades\Http;
use iEXPackages\PluginManager\Contracts\RateParserPluginInterface;
use iEXPackages\PluginManager\DTO\RateParserContext;

final class Parser implements RateParserPluginInterface
{
    public function rates(RateParserContext $context): iterable
    {
        $config = $context->config['rates.source'] ?? [];

        $baseUrl = rtrim((string) ($config['base_url'] ?? 'https://api.example.com'), '/');
        $timeout = (int) ($config['timeout'] ?? 10);

        $secret = $context->plugin
            ->secrets()
            ->where('capability', 'rates.source')
            ->where('key', 'api_key')
            ->where('is_active', true)
            ->first();

        $apiKey = $secret?->encrypted_value;

        $request = Http::timeout($timeout)->acceptJson();

        if ($apiKey) {
            $request = $request->withToken($apiKey);
        }

        $payload = $request
            ->get($baseUrl . '/rates')
            ->throw()
            ->json();

        foreach ((array) data_get($payload, 'data', []) as $row) {
            $from = trim((string) ($row['base'] ?? ''));
            $to = trim((string) ($row['quote'] ?? ''));
            $buy = trim((string) ($row['buy'] ?? $row['rate'] ?? ''));

            if ($from === '' || $to === '' || $buy === '') {
                continue;
            }

            yield [
                'from' => $from,
                'to' => $to,
                'buy' => $buy,
                'sell' => isset($row['sell']) ? (string) $row['sell'] : null,
            ];
        }
    }
}

---

RateParserContext

В метод rates() передаётся объект:

RateParserContext $context

Он содержит данные текущего запуска.

Поле	Что содержит
$context->plugin	Модель установленного плагина
$context->manifest	Manifest текущего плагина
$context->options	Опции конкретного запуска
$context->extra	Дополнительные данные
$context->config	Обычные настройки из config_schema
$context->pluginPath()	Путь к файлу внутри установленного плагина

Пример проверки health-check:

$isHealthCheck = (bool) ($context->options['health_check'] ?? false);

Пример пути к файлу внутри плагина:

$path = $context->pluginPath('data/rates.json');

---

Настройки плагина

Обычные настройки описываются в config_schema.

Они подходят для значений, которые не являются секретными:

• базовый URL API;
• таймаут;
• режим рынка;
• страна;
• валюта;
• флаг включения функции.

Пример:

"config_schema": [
  {
    "key": "base_url",
    "label": "Base URL",
    "type": "url",
    "required": true,
    "default": "https://api.example.com"
  },
  {
    "key": "timeout",
    "label": "Timeout",
    "type": "integer",
    "required": false,
    "default": 10
  },
  {
    "key": "market",
    "label": "Market",
    "type": "select",
    "default": "spot",
    "options": [
      { "value": "spot", "label": "Spot" },
      { "value": "futures", "label": "Futures" }
    ]
  }
]

Использование в PHP:

$config = $context->config['rates.source'] ?? [];

$baseUrl = $config['base_url'] ?? 'https://api.example.com';
$timeout = (int) ($config['timeout'] ?? 10);
$market = $config['market'] ?? 'spot';

Поддерживаемые типы настроек:

text
textarea
url
email
integer
number
boolean
select
json

Секреты плагина

Секретные поля описываются в settings.

Пример:

"settings": [
  {
    "key": "api_key",
    "label": "API key",
    "type": "secret",
    "required": true
  }
]

В iex-plugin.json хранится только схема секретов. Значения секретов в ZIP не хранятся.

Значения секретов:

• вводятся в админке;
• сохраняются отдельно от файлов плагина;
• хранятся в зашифрованном виде;
• не попадают обратно в ZIP;
• не перезаписываются, если при редактировании оставить поле пустым.

Получение секрета в PHP:

$secret = $context->plugin
    ->secrets()
    ->where('capability', 'rates.source')
    ->where('key', 'api_key')
    ->where('is_active', true)
    ->first();

$apiKey = $secret?->encrypted_value;

encrypted_value возвращается уже расшифрованным через Laravel encrypted cast. Дополнительно расшифровывать значение вручную не нужно.

Использование секрета в запросе:

$response = Http::withToken($apiKey)
    ->timeout(10)
    ->get('https://api.example.com/rates')
    ->throw()
    ->json();

Блок rateParser

rateParser управляет поведением курсового плагина.

"rateParser": {
  "discoverOnInstall": true,
  "pairs": []
}

discoverOnInstall

Если значение true, система может запустить плагин при проверке или установке и получить пары из runtime-ответа.

"discoverOnInstall": true

Если значение false, система не будет запускать плагин для первичного поиска пар.

"discoverOnInstall": false

В админке оператор всё равно может выбрать режим установки:

• «По настройке плагина»;
• «Проверить и загрузить пары»;
• «Не загружать при установке».

---

Пары курсов

Есть два способа передать пары курсов системе.

Способ	Когда использовать
rateParser.pairs	Если пары известны заранее
discoverOnInstall + rates()	Если пары нужно получить из API

pairs

rateParser.pairs нужен для первичного создания строк в источниках курсов.

Пример:

"rateParser": {
  "discoverOnInstall": false,
  "pairs": [
    {
      "from": "USD",
      "to": "RUB",
      "amount": "91.25",
      "number_format": 10,
      "status": false
    },
    {
      "from": "EUR",
      "to": "RUB",
      "amount": "98.10",
      "number_format": 10,
      "status": false
    }
  ]
}

Поля пары:

Поле	Назначение
from	Исходная валюта
to	Целевая валюта
amount	Первичное значение курса
type	Тип пары, по умолчанию 0
type_price	Дополнительный тип цены, например buy или sell
number_format	Количество знаков форматирования, от 0 до 18
status	Активность пары

Рекомендуется добавлять новые пары выключенными:

"status": false

Так оператор сможет проверить их перед включением.

Runtime-курсы и pairs

Важно различать pairs и rates().

rateParser.pairs описывает пары, которые можно создать при установке.

Метод rates() возвращает актуальные значения курсов при проверке, health-check и обновлении.

Правильная схема:

rateParser.pairs
└── создаёт список пар

rates()
└── возвращает актуальные значения курсов

Health-check

Health-check запускается из админки кнопкой «Проверить состояние».

Для rates.source система вызывает метод rates() и проверяет, что плагин вернул хотя бы один курс.

В manifest лучше указывать:

"health": {}

Пример обработки health-check:

public function rates(RateParserContext $context): iterable
{
    $isHealthCheck = (bool) ($context->options['health_check'] ?? false);

    if ($isHealthCheck) {
        return [
            ['from' => 'USD', 'to' => 'RUB', 'buy' => '91.25'],
        ];
    }

    return [
        ['from' => 'USD', 'to' => 'RUB', 'buy' => '91.25'],
        ['from' => 'EUR', 'to' => 'RUB', 'buy' => '98.10'],
    ];
}

Миграции плагина

Если плагину нужны свои таблицы, можно добавить миграции.

Описание миграции в manifest:

"migrations": [
  "database/migrations/2026_01_01_000000_create_example_rates_cache.php"
]

Пример файла миграции:

<?php

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class {
    public function up(): void
    {
        Schema::create('example_rates_cache', static function (Blueprint $table): void {
            $table->id();
            $table->string('symbol')->index();
            $table->decimal('bid', 32, 16);
            $table->decimal('ask', 32, 16)->nullable();
            $table->timestamps();
        });
    }
};

Миграции регистрируются при установке, но запускаются отдельно из админки.

JS runtime

Runtime js поддерживается только для совместимости со старыми parser-rate модулями.

Минимальный пример:

module.exports = class Parser {
  async updateRate() {
    return [
      { from: 'USD', to: 'RUB', buy: '91.25' },
      { from: 'EUR', to: 'RUB', buy: '98.10' }
    ];
  }
};

Для новых плагинов используйте PHP runtime.

---

Сборка ZIP

1

Через команду

php artisan iex:plugin-make example-rates --type=parser-rate --runtime=php --title="Example Rates" --zip --force

2

Вручную

Перейдите в папку плагина:

cd storage/app/iex-plugin-templates/example-rates

Соберите архив:

zip -r ../example-rates.zip .

В архиве должна быть структура:

iex-plugin.json
src/Parser.php

Допустимо также:

example-rates/iex-plugin.json
example-rates/src/Parser.php

Система умеет определить одну корневую папку.

Не добавляйте в архив:

• .env;
• .git;
• node_modules;
• vendor;
• логи;
• временные файлы;
• личные ключи;
• пароли;
• дампы базы данных.

---

Проверка плагина в админке

После сборки ZIP проверьте его через панель управления.

Установка плагинов

1. Откройте «Утилиты» — «Установка плагинов».
2. Нажмите «Установить».
3. Выберите тип «Курсы».
4. Загрузите ZIP-архив.
5. Нажмите «Проверить пакет».
6. Проверьте результат предпросмотра.
7. Если отображается «Пакет можно установить», нажмите «Установить».
8. Если у плагина есть секреты или настройки, заполните их.
9. Нажмите «Проверить состояние».
10. Откройте раздел источников курсов и убедитесь, что группа плагина создана.

Проверка через консоль

После установки можно проверить совместимость установленных плагинов:

php artisan iex:plugins-check

Для JSON-вывода:

php artisan iex:plugins-check --json

---

Частые ошибки

Не найден основной файл

Проверьте, что файл существует:

src/Parser.php

Если файл называется иначе, укажите entry явно.

Класс не найден

Для:

"name": "example-rates"

по умолчанию ожидается:

namespace iEXPlugins\ExampleRates;

final class Parser

Если namespace или имя класса другие, укажите class явно.

Класс не реализует интерфейс

Класс должен реализовать:

RateParserPluginInterface

Метод rates ничего не вернул

Метод rates() должен вернуть хотя бы один корректный курс с полями:

from
to
buy

Пары не появились в источниках

Проверьте:

• включён ли discoverOnInstall;
• какой режим выбран при установке;
• вернул ли runtime пары;
• запущена ли очередь задач;
• нет ли ошибок импорта на странице установки плагинов.

Ошибка совместимости

Проверьте:

• core_min;
• core_max;
• php;
• extensions.

---

Рекомендации

Для новых плагинов используйте PHP runtime.

Не храните значения API-ключей в iex-plugin.json.

В settings описывайте только поля секретов.

В config_schema описывайте обычные настройки.

entry и class можно не указывать, если используется стандартная структура.

modules лучше указывать явно, даже если система умеет создать rates.source по умолчанию.

Для health используйте объект:

"health": {}

Курсы возвращайте строками.

Новые пары после импорта должны проверяться оператором вручную.

Перед передачей клиенту всегда проверяйте ZIP через «Установка плагинов».

---

Коротко

Плагин курсов добавляет в iEXExchanger новый внешний источник курсов.

Основной тип плагина:

parser-rate

Основная возможность:

rates.source

Рекомендуемый runtime:

php

Минимальная структура плагина:

iex-plugin.json
src/Parser.php

Главный метод парсера:

public function rates(RateParserContext $context): iterable

Пары можно описать заранее через rateParser.pairs или получить автоматически через discoverOnInstall.

Секреты описываются в settings, обычные настройки — в config_schema.

Готовый плагин нужно собрать в ZIP и проверить через «Утилиты» — «Установка плагинов».