From 00513ef913013b513e61e2c26c3006a0c9e8d139 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 4 Nov 2026 09:41:51 +0000 Subject: [PATCH] Phase 8: redirect the old iForum addresses through a stub module, migration guide and release script Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01MZy45V5RV9nx6Buq8vqKHr --- .gitignore | 1 + CHANGELOG.md | 3 +- README.md | 2 +- docs/MIGRATION.md | 58 +++++++++++++++++++ src/class/LegacyUrl.php | 104 +++++++++++++++++++++++++++++++++++ src/icms_version.php | 4 +- stub/iforum/icms_version.php | 31 +++++++++++ stub/iforum/index.php | 18 ++++++ stub/iforum/rss.php | 18 ++++++ stub/iforum/viewall.php | 18 ++++++ stub/iforum/viewforum.php | 18 ++++++ stub/iforum/viewpost.php | 18 ++++++ stub/iforum/viewtopic.php | 18 ++++++ tests/Unit/LegacyUrlTest.php | 72 ++++++++++++++++++++++++ tools/build-release.sh | 16 ++++++ 15 files changed, 395 insertions(+), 4 deletions(-) create mode 100644 docs/MIGRATION.md create mode 100644 src/class/LegacyUrl.php create mode 100644 stub/iforum/icms_version.php create mode 100644 stub/iforum/index.php create mode 100644 stub/iforum/rss.php create mode 100644 stub/iforum/viewall.php create mode 100644 stub/iforum/viewforum.php create mode 100644 stub/iforum/viewpost.php create mode 100644 stub/iforum/viewtopic.php create mode 100644 tests/Unit/LegacyUrlTest.php create mode 100755 tools/build-release.sh diff --git a/.gitignore b/.gitignore index a183671..8d1d231 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ /.phpunit.cache/ /.phpunit.result.cache /.phpstan/ +/dist/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 730cb1c..09cce95 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## 1.0.0 Alpha (unreleased) -While the module is in development the status carries the phase: 1.0.0 Alpha 7 is phase 7. +While the module is in development the status carries the phase: 1.0.0 Alpha 8 is phase 8. - Phase 0: module skeleton for ImpressCMS 2.0 in IPF mode, install and update routines, English and Dutch language files, CI on PHP 8.2 to 8.5. - Phase 1: data model. 13 IPF objects with handlers (category, forum, moderator, topic, post, attachment, report, suspension, readmark, online, digest, archive, permtemplate), group permissions on categories and forums, counters and cascading deletes through handler events, indexes in `imforum_db_upgrade_1()`, labels in English and Dutch, integration tests against MySQL 5.5, MySQL 5.7 (MyISAM) and MariaDB 10.11. @@ -15,3 +15,4 @@ While the module is in development the status carries the phase: 1.0.0 Alpha 7 i - Editor: the post, forum and category forms use the `dhtmltextarea` control, as the content module does, so the WYSIWYG editor chosen in the site preferences loads (the plain `textarea` control of the IPF ignores the editor). A post written in an editor is stored as HTML (`dohtml` on, line breaks off) and is shown through the purifier; without an editor the text still stays as typed. The quick reply and the moderation forms stay plain textareas. - Phase 7: importer. `admin/import.php` and `Importer` copy the data of a running iForum installation into imforum, keeping every id, and never change iForum: categories, forums, the serialized moderator lists (one row per member), topics (ratings, polls and tags are left out), posts joined with their text (IP addresses become text), edit histories (base64 serialized lists become JSON), attachments from the posts and from the reserved table (names that could leave the upload folder are refused, files are copied and measured), reports, suspensions that have not ended, read marks (one per member and item), digests, the archive, group permissions of the forums and categories under the id of imforum (poll rights are left out), subscriptions that imforum has events for, the preferences that exist in both modules (the `NONE` entry of the subject prefixes is dropped, as imforum counts prefixes from 1) and the cached permission template. The check writes nothing: it reports missing tables and columns, character sets, orphans, posts that grow past 64 KB when converted, missing attachment files and text that looks like UTF-8 in latin1 columns, for which the import can read the bytes as UTF-8. Importing and rolling back ask for a confirmation and run only on a POST with a token. Every import starts by emptying the imforum tables, so an interrupted run is simply repeated; rolling back empties them again and removes the copied rights, subscriptions and files. Afterwards the counters are recounted and `verify()` compares row counts, posts per forum and per topic, a checksum of 200 random posts, the rights and the attachment files. Tests build an old installation, check every table, run the largest case (43,778 posts) and prove that iForum's tables are unchanged. - License: imforum is released under the GNU General Public License version 2 again, like iForum and ImpressCMS. `LICENSE`, `composer.json` (`GPL-2.0-only`), the module definition and the file headers say so. The first phases carried the MIT license. +- Phase 8: migration. A stub module `stub/iforum` replaces the old module folder and sends `index`, `viewforum`, `viewtopic` (also with only a `post_id`), `viewall`, `viewpost` and `rss` to the same page of imforum with a permanent redirect; `LegacyUrl` holds the translation and is covered by unit tests. `docs/MIGRATION.md` describes the steps, the address table, a web server rule and the rollback. `tools/build-release.sh` builds the release zip with both folders. diff --git a/README.md b/README.md index 9475cb0..f44bc8c 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Community forum module for ImpressCMS 2.0, built on the ImpressCMS Persistable Framework (IPF). imforum is the successor of iForum: same features, new code, and an importer that takes over the data of a running iForum installation. -Status: phase 7 (importer), module version 1.0.0 Alpha 7. Members start topics, reply (with a quick reply under the topic), quote, edit and delete their own posts, attach files and follow topics and forums by notification; guests can post where the group permissions allow it, behind a captcha. Posts wait for a moderator when the group lacks forum_noapprove. Moderators of a forum lock, pin and feature topics, move, merge and split them, delete topics, approve waiting posts, handle reports from members and suspend members, all from the front end through `moderate.php`; members report posts through `report.php`. Two autotasks (Systeem > Autotasks, daily by default) send a digest of new topics and posts to members who subscribe to it and clean up old read marks, the visitors list and ended suspensions. Categories, forums, moderators, permissions, reports, suspensions, digests, the archive and pruning are managed from the admin area. The import page copies the data of a running iForum installation into imforum: check, import, verify and roll back. +Status: phase 8 (migration), module version 1.0.0 Alpha 8. Members start topics, reply (with a quick reply under the topic), quote, edit and delete their own posts, attach files and follow topics and forums by notification; guests can post where the group permissions allow it, behind a captcha. Posts wait for a moderator when the group lacks forum_noapprove. Moderators of a forum lock, pin and feature topics, move, merge and split them, delete topics, approve waiting posts, handle reports from members and suspend members, all from the front end through `moderate.php`; members report posts through `report.php`. Two autotasks (Systeem > Autotasks, daily by default) send a digest of new topics and posts to members who subscribe to it and clean up old read marks, the visitors list and ended suspensions. Categories, forums, moderators, permissions, reports, suspensions, digests, the archive and pruning are managed from the admin area. The import page copies the data of a running iForum installation into imforum: check, import, verify and roll back. ## Requirements diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md new file mode 100644 index 0000000..fcc3bf2 --- /dev/null +++ b/docs/MIGRATION.md @@ -0,0 +1,58 @@ +# Moving from iForum to imforum + +imforum runs next to iForum while you import, so the old forum keeps working until you are satisfied. iForum is never changed by the import. + +## Before you start + +- ImpressCMS 2.0 on PHP 8.2 or newer and MySQL 5.5.3 or newer, with the PDO driver (`XOOPS_DB_TYPE` is `pdo.mysql`). +- A backup of the database and of `uploads/iforum`. +- The tables of imforum are created as utf8mb4. On MySQL 5.5 the check refuses tables in another character set and says how to convert them. + +## Steps + +1. Copy the folder `modules/imforum` of the release to your site and install it in System > Modules. Leave iForum installed. +2. Open imforum > Import and press **Check**. It writes nothing. Fix what it reports (missing attachment files are warnings, missing tables are errors). +3. Press **Import**. Every run first empties the imforum tables, so an interrupted run is simply repeated. All ids stay the same. +4. Press **Verify**. It compares row counts, posts per forum and per topic, a checksum of 200 random posts, the rights and the files. +5. Walk through the forum as a member and as a guest. Posts, forums and attachments have the same ids as before. +6. Set up the old addresses (next section), then uninstall iForum. + +## Old addresses + +Links to `modules/iforum/viewtopic.php?topic_id=12` keep working through a stub module: + +1. Uninstall iForum in System > Modules and delete the folder `modules/iforum`. +2. Copy the folder `modules/iforum` of the release in its place. It holds six small scripts and no data. Do **not** install it in System > Modules: the scripts redirect without the module being installed. +3. Open an old address. It answers with a permanent redirect (301) to the same page of imforum. + +| Old | New | +| --- | --- | +| `index.php` | `index.php` | +| `viewforum.php?forum=7&start=20` | `forum.php?forum=7&start=20` | +| `viewtopic.php?topic_id=12` | `topic.php?topic=12` | +| `viewtopic.php?topic_id=12&post_id=99` | `topic.php?topic=12&post=99` | +| `viewtopic.php?post_id=99` | the topic of that post, jumping to it | +| `viewtopic.php?topic_id=12&viewmode=thread` | `topic.php?topic=12&mode=tree` | +| `viewall.php?type=unread` or `digest` | `viewall.php?type=unread` or `digest`; other types show the latest topics | +| `viewpost.php` | `viewall.php` | +| `rss.php?f=5` | `rss.php?forum=5` (several forums, or none: all forums) | + +Sort and filter options of the old lists (`sortname`, `sortorder`, `since`) are dropped. Without the stub folder the old addresses give a 404; a web server rule can do the same job: + +```apache +RewriteEngine On +RewriteCond %{QUERY_STRING} (?:^|&)topic_id=([0-9]+) +RewriteRule ^modules/iforum/viewtopic\.php$ /modules/imforum/topic.php?topic=%1 [R=301,L] +RewriteCond %{QUERY_STRING} (?:^|&)forum=([0-9]+) +RewriteRule ^modules/iforum/viewforum\.php$ /modules/imforum/forum.php?forum=%1 [R=301,L] +``` + +Links inside imported posts are not rewritten; they use the old addresses and so go through the redirects. + +## Rolling back + +Until you uninstall iForum nothing is lost: **Roll back** on the import page empties the imforum tables and removes the copied files, rights and subscriptions. After uninstalling iForum, restore the database backup to return. + +## Translations + +English and Dutch ship with the module. Other languages come from Crowdin (`crowdin.yml` maps the codes to the ImpressCMS folder names); download them into `language//`. A missing file falls back to English. diff --git a/src/class/LegacyUrl.php b/src/class/LegacyUrl.php new file mode 100644 index 0000000..fff7fbf --- /dev/null +++ b/src/class/LegacyUrl.php @@ -0,0 +1,104 @@ + $query the old $_GET + * @param (callable(int): int)|null $topicOfPost finds the topic of a post, 0 when unknown + */ + public static function target(string $script, array $query, ?callable $topicOfPost = null): string { + $int = static function (string $name) use ($query): int { + $value = $query[$name] ?? 0; + return is_scalar($value) ? max(0, (int) $value) : 0; + }; + switch ($script) { + case 'viewforum': + return self::build('forum', ['forum' => $int('forum'), 'start' => $int('start')], $int('forum') > 0); + + case 'viewtopic': + $topicId = $int('topic_id'); + $postId = $int('post_id'); + if ($topicId < 1 && $postId > 0 && $topicOfPost !== null) { + $topicId = max(0, $topicOfPost($postId)); + } + if ($topicId < 1) { + // only a forum is known: go there, else to the index + return $int('forum') > 0 ? self::build('forum', ['forum' => $int('forum')], true) : 'index.php'; + } + $viewmode = (string) ($query['viewmode'] ?? ''); + return self::build('topic', [ + 'topic' => $topicId, + 'post' => $postId, + 'start' => $postId > 0 ? 0 : $int('start'), + 'mode' => in_array($viewmode, ['thread', 'tree'], true) ? 'tree' : '', + ], true); + + case 'viewall': + $type = (string) ($query['type'] ?? ''); + return self::build('viewall', [ + 'type' => in_array($type, ['unread', 'digest'], true) ? $type : '', + 'start' => $int('start'), + ], true); + + case 'viewpost': + // the list of the latest posts has no counterpart: the latest topics are the nearest + return 'viewall.php'; + + case 'rss': + // the old feed took a pipe separated list; imforum has one feed per forum or all + $forums = array_values(array_filter(array_map('intval', explode('|', (string) ($query['f'] ?? ''))), static fn (int $id): bool => $id > 0)); + return self::build('rss', ['forum' => count($forums) === 1 ? $forums[0] : 0], true); + + default: + return 'index.php'; + } + } + + /** + * Page and query; the zero and empty values are left out + * + * @param array $query + */ + private static function build(string $page, array $query, bool $valid): string { + if (!$valid) { + return 'index.php'; + } + $query = array_filter($query, static fn ($value): bool => $value !== '' && $value !== 0); + return $page . '.php' . ($query ? '?' . http_build_query($query, '', '&') : ''); + } + + /** + * Sends the visitor on with a permanent redirect + * + * Called from the scripts of the stub module. Without imforum there is + * nothing to go to, so the visitor ends up on the home page. + */ + public static function redirect(string $script): never { + $base = defined('IMFORUM_URL') ? IMFORUM_URL : ICMS_URL . '/modules/imforum/'; + $lookup = static function (int $postId): int { + $post = icms_getModuleHandler('post', 'imforum')->get($postId); + return is_object($post) && !$post->isNew() ? (int) $post->getVar('topic_id', 'e') : 0; + }; + $target = $base . self::target($script, $_GET, $lookup); + header('Location: ' . $target, true, 301); + exit; + } +} diff --git a/src/icms_version.php b/src/icms_version.php index 148d28a..4908b74 100644 --- a/src/icms_version.php +++ b/src/icms_version.php @@ -19,8 +19,8 @@ $modversion = [ 'name' => _MI_IMFORUM_NAME, 'version' => '1.0.0', - 'status' => 'Alpha 7', - 'status_version' => '1.0.0 Alpha 7', + 'status' => 'Alpha 8', + 'status_version' => '1.0.0 Alpha 8', 'date' => '25 October 2026', 'description' => _MI_IMFORUM_DESC, 'author' => 'fiammybe', diff --git a/stub/iforum/icms_version.php b/stub/iforum/icms_version.php new file mode 100644 index 0000000..8b36199 --- /dev/null +++ b/stub/iforum/icms_version.php @@ -0,0 +1,31 @@ + 'iForum (redirects to imforum)', + 'version' => '1.0.0', + 'status' => 'Stub', + 'status_version' => '1.0.0 Stub', + 'description' => 'Sends the old iForum addresses on to imforum.', + 'author' => 'fiammybe', + 'license' => 'GNU GPL v2, see LICENSE', + 'official' => false, + 'dirname' => 'iforum', + 'hasMain' => 0, + 'hasAdmin' => 0, + 'hasSearch' => 0, + 'hasComments' => 0, + 'hasNotification' => 0, + 'sub' => [], +]; diff --git a/stub/iforum/index.php b/stub/iforum/index.php new file mode 100644 index 0000000..94e8892 --- /dev/null +++ b/stub/iforum/index.php @@ -0,0 +1,18 @@ +, string}> + */ + public static function addresses(): array + { + return [ + 'index' => ['index', ['cat' => '2'], 'index.php'], + 'forum' => ['viewforum', ['forum' => '7'], 'forum.php?forum=7'], + 'forum page, sort options dropped' => ['viewforum', ['forum' => '7', 'start' => '20', 'sortname' => 'u.uname', 'since' => '5'], 'forum.php?forum=7&start=20'], + 'forum without id' => ['viewforum', [], 'index.php'], + 'topic' => ['viewtopic', ['topic_id' => '12', 'forum' => '3'], 'topic.php?topic=12'], + 'topic page' => ['viewtopic', ['topic_id' => '12', 'start' => '30'], 'topic.php?topic=12&start=30'], + 'topic thread view' => ['viewtopic', ['topic_id' => '12', 'viewmode' => 'thread'], 'topic.php?topic=12&mode=tree'], + 'topic compact view is flat' => ['viewtopic', ['topic_id' => '12', 'viewmode' => 'compact'], 'topic.php?topic=12'], + 'topic and post' => ['viewtopic', ['topic_id' => '12', 'post_id' => '99', 'start' => '30'], 'topic.php?topic=12&post=99'], + 'only a forum known' => ['viewtopic', ['forum' => '3'], 'forum.php?forum=3'], + 'nothing known' => ['viewtopic', [], 'index.php'], + 'latest' => ['viewall', ['type' => 'new'], 'viewall.php'], + 'unread' => ['viewall', ['type' => 'unread', 'start' => '10'], 'viewall.php?type=unread&start=10'], + 'digest' => ['viewall', ['type' => 'digest'], 'viewall.php?type=digest'], + 'posts list' => ['viewpost', ['uid' => '4'], 'viewall.php'], + 'one feed' => ['rss', ['f' => '5'], 'rss.php?forum=5'], + 'feeds of several forums' => ['rss', ['f' => '5|6'], 'rss.php'], + 'all feeds' => ['rss', ['c' => '1'], 'rss.php'], + 'unknown script' => ['whatever', [], 'index.php'], + 'array value is ignored' => ['viewforum', ['forum' => ['1']], 'index.php'], + ]; + } + + /** + * @param array $query + */ + #[DataProvider('addresses')] + public function testAddress(string $script, array $query, string $expected): void + { + self::assertSame($expected, \mod_imforum_LegacyUrl::target($script, $query)); + } + + public function testTheTopicOfAPostIsLookedUp(): void + { + $lookup = static fn (int $postId): int => $postId === 99 ? 12 : 0; + + self::assertSame('topic.php?topic=12&post=99', \mod_imforum_LegacyUrl::target('viewtopic', ['post_id' => '99'], $lookup)); + self::assertSame('forum.php?forum=3', \mod_imforum_LegacyUrl::target('viewtopic', ['post_id' => '5', 'forum' => '3'], $lookup)); + } + + public function testEveryScriptHasAStubFile(): void + { + foreach (\mod_imforum_LegacyUrl::SCRIPTS as $script) { + self::assertFileExists(dirname(__DIR__, 2) . '/stub/iforum/' . $script . '.php'); + } + } +} diff --git a/tools/build-release.sh b/tools/build-release.sh new file mode 100755 index 0000000..558e30c --- /dev/null +++ b/tools/build-release.sh @@ -0,0 +1,16 @@ +#!/bin/sh +# Builds dist/imforum-.zip: the module folder `imforum` and the redirect stub `iforum` +set -e +cd "$(dirname "$0")/.." +version=$(php -r 'define("ICMS_ROOT_PATH", "x"); $modversion = []; $s = file_get_contents("src/icms_version.php"); preg_match("/\x27status_version\x27 => \x27([^\x27]+)\x27/", $s, $m); echo str_replace(" ", "-", $m[1]);') +work=$(mktemp -d) +mkdir -p "$work/modules" dist +cp -r src "$work/modules/imforum" +cp -r stub/iforum "$work/modules/iforum" +cp LICENSE README.md CHANGELOG.md "$work/modules/imforum/" +cp -r docs "$work/modules/imforum/docs" +out="$(pwd)/dist/imforum-$version.zip" +rm -f "$out" +(cd "$work" && zip -qr "$out" modules) +rm -rf "$work" +echo "$out"