Module Anatomy

coremio/modules/{Type}/{Name}/
├── {Name}.php          # REQUIRED: the class, same name as the directory
├── config.php          # returns an array; settings, metadata, field definitions
├── logo.png            # or .svg/.webp/.jpg; resolved by name when config does not name one
├── hooks.php           # Hook::add() registrations, included on EVERY request
├── AdminArea.php       # own admin page, registered from router.php
├── router.php          # include + ModuleAdminArea::register()
├── lang/
│   ├── en.php          # REQUIRED in practice: the fallback language
│   └── tr.php          # one file per translated language
├── pages/              # settings and management markup, resolved by page name
├── views/              # same role, alternative directory name
├── controllers/        # named entry points reached through the controller dispatcher
├── assets/
│   ├── style/          # css
│   ├── js/             # javascript
│   └── images/         # interface images, not the logo
└── src/                # your own helper classes, NOT autoloaded

// Context binding. Each takes an id OR the already-loaded record; an int is fetched for you.
public function set_service(array|int $service = []): void;
public function set_product(array|int $product = []): void;
public function set_order(array|int $order = []): void;

// Persist $this->options back onto the bound service. False when nothing is bound.
public function save_options(): bool;

// Rewrite config.php. $auto_status = true flips status on when a settings array is present.
protected function save_config($data = [], $auto_status = true);

// One log row per provider call, shown in the panel's action history.
protected function save_log($action = '', $request = '', $response = '', $processed = ''): int|bool;

// Encrypt with the module's crypt sub-key; $key overrides it for one call.
protected function encode_str(string $str = '', string $key = ''): string;
protected function decode_str(string $str = '', string $key = ''): string;

// Resolved logo URL, or an empty string.
public function logo(): string;

// Metered metric limits enabled on the bound service, keyed by metric type.
protected function enabled_metrics(): array;
protected function enabled_metric_values(): array;
protected function reapply_enabled_metrics(): void;

// Data attributes for a dropdown that loads its options from one of your methods.
protected function method_url_data(string $method): array;

// Dispatch "reset-password" to handle_reset_password(). Returns null when it does not exist.
protected function use_method($param = '');

// Add-on values for one option, multiplied by quantity unless the param opts out.
public function resolveAddonConfigurable(array $moduleParams, int $quantity = 0): array;

// Properties: $config, $lang, $dir, $url, $area_link, $_name, $user, $admin, $error.
public function __construct();

// Render views/{file}.php with $variables extracted into it. Returns the markup.
protected function view($file = '', $variables = []): string;

// Privilege keys this addon adds to the admin role screen.
public function privileges();

// Called by the addon settings screen: $pFields is the posted settings,
// $accessPs the posted privilege selection.
public function save_settings($pFields, $accessPs): bool;

// Enable or disable from the addon list.
public function change_addon_status($arg = '');

// Rewrite config.php. Note the single argument: no auto-status flag here.
public function save_config($data = []): bool;

// Same crypt helpers, but the addon base defaults the sub-key to 'system'.
protected function encode_str(string $str = '', string $key = ''): string;
protected function decode_str(string $str = '', string $key = ''): string;

public function use_default_settings($formElements = null);
public function isEnabled();

namespace WISECP\Modules\Registrars;

use Exception;
use Language;
use RegistrarModule;
use WISECP\Modules\Registrars\AcmeDomains\ApiClient;

class AcmeDomains extends RegistrarModule
{
    private ?ApiClient $api = null;

    // No constructor. The base one already set $_name, $_type, $dir, $url, $config and $lang.
    // Build the client lazily instead: the service is bound AFTER construction, so anything
    // that needs $this->service cannot run here.
    private function api(): ApiClient
    {
        if ($this->api) return $this->api;

        // src/ is not autoloaded, so the file is included explicitly.
        include_once $this->dir . 'src' . DS . 'ApiClient.php';

        $settings = $this->config['settings'] ?? [];

        $this->api = new ApiClient(
            (string) ($settings['username'] ?? ''),
            $this->decode_str((string) ($settings['apiKey'] ?? '')),
        );

        return $this->api;
    }

    // NOT create(). The base class owns create() and dispatches to register() or
    // transfer() depending on whether an EPP code is present. Overriding create()
    // would drop the transfer branch and both of its hooks.
    public function register(): array|bool
    {
        // The bound record carries the ordered domain in options; service['name']
        // is the fallback. There is no 'domain' column on the service itself.
        $domain = (string) ($this->options['domain'] ?? $this->service['name'] ?? '');
        if ($domain === '') throw new Exception(Language::gc("acme/error-no-domain"));

        // 'year' is the registration length. service['period'] is the billing cycle
        // string ('y', 'm', 'none'), never a number of years.
        $year = (int) ($this->options['year'] ?? $this->service['period_time'] ?? 1) ?: 1;

        $response = $this->api()->register($domain, $year);

        // Every provider call is recorded; api_url is lifted into its own column.
        $this->save_log('register', ['api_url' => $this->api()->last_url, 'domain' => $domain], $response);

        if (!($response['ok'] ?? false))
            throw new Exception($response['message'] ?? Language::gc("acme/error-refused"));

        return true;
    }
}

$module = Modules::getInstance("Registrars", "AcmeDomains");
if (!$module) throw new Exception(Language::gc("modules/error-not-found"));

// Binding is a separate step, and it is what fills $service, $product, $user and $options.
$module->set_service($serviceId);

try {
    // The caller always asks for create(). On a registrar that is the base method,
    // which routes to register() or transfer() and runs the domain hooks around it.
    $result = $module->create();
}
catch (\Throwable $e) {
    // A module reports failure by throwing; the caller turns the message into a response.
    return $operation->output(['status' => "error", 'message' => $e->getMessage()]);
}

// Module state the module changed goes back to the service through its own helper.
$module->save_options();