Module Lifecycle

// Enable path, in this order. activate() runs first, then enable().
// Returning false leaves the module disabled and nothing is written.
public function activate(): bool;
public function enable(): bool;

// Disable path, in this order.
public function deactivate(): bool;
public function disable(): bool;

// Runs before the module directory is removed. Returning false aborts the delete.
// This no-argument boolean form is the ADDON one.
public function uninstall(): bool;

// The Authentication type reuses the name with a different shape: the stored
// enrolment data is passed in, and an array is returned. Only 'error' aborts.
public function uninstall(array $data = []): array;   // ['status' => 'successful']

// The Test button. Two shapes, and the caller decides which one you get:
// social login providers are called with NO argument (abstract on the base),
// registrars are called WITH the merged configuration as the only argument.
public function testConnection(): bool;                  // SocialAuth
public function testConnection($config = []): bool;      // Registrars

// Already implemented on the addon base: it runs the four methods above and then
// writes the new status into config.php. Override only to replace that behaviour.
public function change_addon_status($arg = '');

public function change_addon_status($arg = '')
{
    $status = $arg == "enable";
    $apply  = true;

    if ($status && method_exists($this, 'activate'))    $apply = $this->activate();
    if ($status && method_exists($this, 'enable'))      $apply = $this->enable();
    if (!$status && method_exists($this, 'deactivate')) $apply = $this->deactivate();
    if (!$status && method_exists($this, 'disable'))    $apply = $this->disable();

    // The flag is written LAST, and only when the module agreed.
    if ($apply) {
        $config           = $this->config;
        $config["status"] = $status;
        $this->save_config($config);
    }

    return $apply;
}

$key    = (string) Filter::init("POST/module", "route");
$status = (int) Filter::init("POST/status", "rnumbers");

$instance = Modules::getInstance("Addons", $key);

if (!method_exists($instance, "change_addon_status"))
    throw new Exception("Module class does not have a method named change_addon_status.");

$status = $status ? "enable" : "disable";

// A thrown Exception travels straight out as the error message. A false return is
// the older path: the caller then reads the legacy error property for a reason.
$result = $instance->change_addon_status($status);
if (!$result) throw new Exception($instance->error ?: "Unknown error");

User::addAction($adata["id"], "alteration", "change-addon-status-" . $status, ['module' => $key]);

Hook::run('action:addon.status_changed', $key, $status);

public function enable(): bool
{
    // Idempotent on purpose: enable() runs again on every re-enable and after an update.
    $this->check_database();

    return true;
}

/** Only ever adds. Never drops, never rewrites an existing column. */
private function check_database(): void
{
    if (!\WDB::hasTable("Acme_events"))
        \WDB::exec('CREATE TABLE `Acme_events` ('
            . '`id` INT(11) UNSIGNED NOT NULL AUTO_INCREMENT,'
            . '`service_id` INT(11) UNSIGNED NOT NULL DEFAULT 0,'
            . '`payload` TEXT NULL DEFAULT NULL,'
            . 'PRIMARY KEY (`id`)'
            . ') ENGINE = InnoDB CHARSET=utf8mb4 COLLATE utf8mb4_unicode_ci;');

    // Columns added after the table first shipped are checked one by one.
    $col = \WDB::query("SHOW COLUMNS FROM `Acme_events` LIKE 'created_at'");
    if (!($col ? \WDB::getAssoc($col) : false))
        \WDB::exec("ALTER TABLE `Acme_events` ADD `created_at` INT(11) UNSIGNED NOT NULL DEFAULT '0'");
}

public function disable(): bool
{
    // Nothing is dropped here. Disabling is reversible, and an operator who turns the
    // module off for an afternoon must not lose a year of rows.
    return true;
}

public function uninstall(): bool
{
    // Refuse rather than destroy silently when there is still something to lose.
    // select() returns the BUILDER, so build() and getAssoc() are called on it.
    // Handing the builder to WDB::getAssoc() as an argument is a fatal: that
    // parameter expects a PDOStatement, which is what WDB::query() gives back.
    $stmt = \WDB::select('COUNT(id) AS total')->from('Acme_events');
    $rows = $stmt->build() ? (int) (($stmt->getAssoc() ?: [])['total'] ?? 0) : 0;

    if ($rows > 0 && !(int) \Filter::init("POST/purge", "rnumbers"))
        throw new \Exception($this->lang['error-uninstall-has-data'] ?? 'The module still holds records.');

    \WDB::exec("DROP TABLE IF EXISTS `Acme_events`");

    return true;
}

// Runs on EVERY request, for this module, enabled or not. Keep it to registrations.
Hook::add('gate:module.addon_delete', 1, function ($key) {
    if ($key !== 'Acme') return '';

    $stmt = WDB::select('COUNT(id) AS cnt')->from('Acme_events');
    $stmt->where('processed', '=', 0);

    $open = $stmt->build() ? (int) (($stmt->getAssoc() ?: [])['cnt'] ?? 0) : 0;

    // A non-empty string is the refusal, and it is what the operator reads.
    return $open > 0 ? 'Acme still has ' . $open . ' unprocessed events.' : '';
});

Hook::add('action:addon.status_changed', 1, function ($key, $status) {
    if ($key !== 'Acme') return;

    Cache::getInstance()->clear(['acme']);
});