Writing a Currency Module

// 1. coremio/helpers/Money.php: the only rate path, used by the sync task
$instance = self::currency_module();               // configured module, else OpenRates
if (!$instance) return "Currency module not available.";
$rates = $instance->exchange_rates($from, $to);
if (!$rates) return $instance->error;              // the module's own message reaches the operator

// 2. coremio/operations/AdminFinancialCurrencies.php: settings save, then the test button
$instance = Modules::getInstance("Currency", $module);
if ($instance && method_exists($instance, "save_config")) $instance->save_config($module_data[$module]);
// ...
if (!method_exists($instance, "exchange_rates")) throw new Exception("Module does not implement exchange_rates().");
$instance->config = array_replace_recursive($instance->config, $module_data[$module]);   // unsaved form values
$rates = $instance->exchange_rates($localCode, $targets);

// 3. coremio/api/Resources/Admin/Concerns/FinancialCurrencies.php: the same two, over the API

Acme.php        namespace WISECP\Modules\Currency; class Acme  (no extends)
config.php      a FLAT array, not the meta/settings split other module types use
lang/en.php
lang/tr.php

<?php
namespace WISECP\Modules\Currency;

class Acme
{
    public string  $name   = "Acme";
    public ?array  $config = null;
    public ?array  $lang   = null;
    public ?string $error  = null;      // the caller reads this when you return false

    public function __construct()
    {
        // Global classes need the leading backslash inside this namespace,
        // otherwise PHP looks for WISECP\Modules\Currency\Modules.
        $this->config = \Modules::Config("Currency", $this->name);
        $this->lang   = \Modules::Lang("Currency", $this->name);
    }
}

// REQUIRED
public function exchange_rates(string $from = '', array $to = []): array|false;

// REQUIRED once the module has any setting
public function save_config(array $data = []): bool;

// OPTIONAL: markup for the currency settings screen
public function page_settings(): string;

// Public state the callers read directly
public string  $name;
public ?array  $config;    // overwritten in memory by the test button
public ?array  $lang;
public ?string $error;     // surfaced to the operator when exchange_rates() returns false

$rates = Money::get_exchange_rates($localCode, $targets);

if (!is_array($rates))
    return ['success' => false, 'result' => ['error' => is_string($rates) ? $rates : 'invalid-response']];

// Extension point: inject a currency the provider cannot quote, or override one.
Hook::runRefs('filter:money.exchange_rates_fetch', $rates, $localCode, $targets);

// Uppercase code => currency id, so a provider that answered with everything
// still updates only the currencies this installation actually has.
$codeToId = [];
foreach ($targets as $cid => $code) $codeToId[strtoupper($code)] = (int) $cid;

foreach ($rates as $code => $rate) {
    $codeUp = strtoupper((string) $code);
    $rate   = (float) $rate;

    if (!isset($codeToId[$codeUp])) continue;          // not a currency here: ignored
    if ($rate <= 0 || $rate > 999999999999.99999999) { $skipped++; continue; }   // sanity guard

    WDB::update('currencies', ['rate' => $rate])->where('id', '=', $codeToId[$codeUp])->save();
}

Hook::run('action:money.exchange_rates_updated', $changes, $localCode);

public function exchange_rates(string $from = '', array $to = []): array|false
{
    $apiKey = (string) ($this->config["api_key"] ?? '');

    if ($apiKey === '') {
        $this->error = "Acme api_key is not configured.";
        return false;
    }

    $url = "https://api.example.com/v1/" . urlencode($apiKey) . "/latest/" . urlencode(strtoupper($from));

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 15);

    $response = curl_exec($ch);
    if ($response === false) $this->error = curl_error($ch) ?: "Currency provider request failed.";
    curl_close($ch);

    // Log BEFORE the early returns: an operator debugging a bad key needs to
    // see the request that produced the failure, not only the failure.
    \Modules::save_log("Currency", $this->name, "exchange", [
        'api_url' => $url,
        'from'    => $from,
        'to'      => $to,
    ], $response, $this->error);

    if ($this->error) return false;

    $decoded = \Utility::jdecode(trim((string) $response), true);

    if (!is_array($decoded) || ($decoded["result"] ?? '') !== 'success') {
        $this->error = (string) ($decoded["error-type"] ?? 'Acme returned an error.');
        return false;
    }

    // Uppercase keys, float values. $to is NOT used as a filter: the sync
    // keeps what it recognises and ignores the rest.
    $result = [];
    foreach ((array) ($decoded["conversion_rates"] ?? []) as $code => $rate)
        $result[strtoupper((string) $code)] = (float) $rate;

    return $result;
}

public function page_settings(): string
{
    $apiKey = htmlspecialchars((string) ($this->config["api_key"] ?? ''), ENT_QUOTES);

    // The input NAME is the contract with the save operation:
    // module_data[Acme][api_key] arrives as $data['api_key'] in save_config().
    return '<div class="row mb-0 align-items-center">'
        . '<label for="acme-apikey" class="col-sm-3 col-form-label fw-semibold">API Key</label>'
        . '<div class="col-sm-9">'
        . '<input type="text" class="form-control" id="acme-apikey"'
        . ' name="module_data[Acme][api_key]" value="' . $apiKey . '" placeholder="api_key">'
        . '</div></div>';
}

public function save_config(array $data = []): bool
{
    // Merge, do not replace: a partial post must not wipe the other keys.
    $merged = array_replace_recursive($this->config ?: [], $data);

    // file_write() invalidates the opcode cache for a .php target, which is why
    // the saved value is readable on the very next request.
    return (bool) \FileManager::file_write(
        __DIR__ . DS . "config.php",
        \Utility::array_export($merged, ['pwith' => true])
    );
}

<?php
return [
    'api_key'   => '',
    'help-link' => 'https://example.com',
];