Working Without Touching the Core

Acme.php            # the module class the core instantiates
config.php          # settings, written by the module, never by a release
hooks.php           # auto-included: every Hook::add lives here
router.php          # auto-included for admin routing: registers the admin area
AdminArea.php       # your own admin page(s)
lang/en.php         # your strings, keyed however you like
cronjobs/Sync.php   # your scheduled handler, registered from hooks.php
src/AcmeClient.php  # plain classes of your own, constructed with `new`

// coremio/classes/Hook.php
public static function add($name, $priority, $properties = []): void;

// coremio/classes/Modules.php - load config without including the class ($nominc = true),
// then read it. Both are needed for a cheap "is my module on?" guard in hooks.php.
public static function Load($type = '', $name = '', $nominc = false, $status = '');
public static function Config($type, $module);
public static function getInstance(string $type, string $name, array $params = []): ?object;

// coremio/classes/ModuleAdminArea.php - called from the module's router.php.
public static function register(string $areaClass): void;
public static function get(string $type, string $name): ?array;

// coremio/helpers/CronJobQueue.php - called from a register:cronjobs listener.
public static function register(string $type, string $handlerClass): void;
public static function dispatch(string $type, array $payload = [], array $opts = []): int;

// coremio/cronjobs/CronJobHandler.php - an INTERFACE, so implement it, do not extend it.
// Return true for success, false to fail and be retried, or ['success' => bool,
// 'result' => array] to hand the admin Results tab a payload as well.
public function handle(array $payload, array $job): bool|array;

// [0] METHOD    [1] pattern (full path after /api/v1, {x} captures)
// [2] Group     [3] Action   [4] public?  [5] authOnly?  [6] audience
$routes[] = ['GET', 'acme/status', 'Module:Addons/Acme', 'status', false, true, 'admin'];

// Group "Module:{Type}/{Name}" dispatches to the module instance method
//   api_{Action}(WISECP\Api\Core\Request $request, array $match)
// and method_exists decides: there is no __call fallback. A typo in [3] is a 404,
// not an error you can see.
//
// [4] public = true   → no credential at all; the module polices its own access
// [5] authOnly = true → a valid credential is enough, no scope is checked (the default
//                       on the free surface, because module scopes are not in the catalog)
// [6] audience        → 'admin' | 'client' | 'any', only consulted when public is false

<?php

// The cheap guard: config only, class not included. Everything below is inside the if,
// so a disabled module registers nothing and costs one file read.
Modules::Load('Addons', 'Acme', true);
$acme = Modules::Config('Addons', 'Acme') ?: [];

if ($acme['status'] ?? false) {

    // 1. An AJAX action on a page this module does not own. Reached as
    //    operation=acme_resync on the services controller. Nothing wraps this call,
    //    so the privilege check is ours to make.
    Hook::add('register:admin.operations', 1, function ($cname, $operation) {
        if ($operation !== 'acme_resync')       return null;
        if ($cname !== 'services')              return null;
        if (!Admin::isPrivilege(['SERVICES_OPERATION']))
            return ['status' => 'error', 'message' => Language::gc('acme/no-privilege')];

        return Modules::getInstance('Addons', 'Acme')->resync_request();
    });

    // 2. An endpoint of our own on the credentialed admin surface.
    Hook::add('filter:api.routes', 1, function (&$routes, &$audience) {
        if ($audience !== 'admin') return;
        $routes[] = ['GET', 'acme/status', 'Module:Addons/Acme', 'status', false, true, 'admin'];
    });

    // 3. A scheduled task. The file is included here, not at boot: the cron registry
    //    only scans the core directory.
    Hook::add('register:cronjobs', 1, function () {
        include_once __DIR__ . DS . 'cronjobs' . DS . 'Sync.php';
        CronJobQueue::register(\WISECP\Modules\Addons\Acme\CronJobs\Sync::TYPE,
                               \WISECP\Modules\Addons\Acme\CronJobs\Sync::class);
    });

    // 4. Reword one component string without editing a language file. By reference,
    //    and only ever for the exact key we own the opinion about.
    Hook::add('filter:i18n.translation', 1, function (&$text, $key, $lang) {
        if ($key !== 'admin/services/status-active') return;
        $text = Language::gc('acme/status-live');
    });
}

public function resync_request(): array
{
    $id = (int) Filter::init('POST/id', 'rnumbers');
    if (!$id) return ['status' => 'error', 'message' => Language::gc('acme/id-required')];

    // Throwing is the module's way of reporting failure; here we are answering an
    // AJAX call directly, so the error is shaped by hand instead.
    try {
        $rows = $this->client()->resync($id);
    }
    catch (\Throwable $e) {
        return ['status' => 'error', 'message' => $e->getMessage()];
    }

    return ['status' => 'successful', 'message' => Language::gc('acme/resynced'), 'count' => $rows];
}

// The API endpoint registered above lands here. The name is api_ plus the Action
// from the tuple, and method_exists is the only thing that decides.
public function api_status(\WISECP\Api\Core\Request $request, array $match): array
{
    return ['data' => ['enabled' => true, 'last_sync' => Config::getd('acme_last_sync')]];
}

// coremio/modules/Addons/Acme/router.php
namespace WISECP\Modules\Addons\Acme;

include_once __DIR__ . DS . 'AdminArea.php';

\ModuleAdminArea::register(AdminArea::class);

// coremio/modules/Addons/Acme/AdminArea.php
namespace WISECP\Modules\Addons\Acme;

class AdminArea extends \ModuleAdminArea
{
    public static function manifest(): array
    {
        return [
            'title'      => 'Acme',
            'slug'       => 'acme',
            'privileges' => ['TOOLS_ADDONS'],
            'menu'       => ['path' => ['TOOLS'], 'name' => 'Acme'],
        ];
    }

    // /{admin}/acme          → page_home()
    // /{admin}/acme/report   → page_report()
    public function page_home(array $params): string|array
    {
        return ['content' => '<p>Acme</p>', 'page_title' => 'Acme'];
    }

    // POST to the same URL with operation=refresh
    public function op_refresh(\Operation $operation): bool
    {
        $operation->demo();

        return $operation->output(['status' => 'successful']);
    }
}