Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@
/.phpunit.cache/
/.phpunit.result.cache
/.phpstan/
/dist/
3 changes: 2 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
58 changes: 58 additions & 0 deletions docs/MIGRATION.md
Original file line number Diff line number Diff line change
@@ -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/<name>/`. A missing file falls back to English.
104 changes: 104 additions & 0 deletions src/class/LegacyUrl.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
<?php
/**
* Translates the addresses of the old iForum module into those of imforum
*
* The stub module that takes the place of iForum after the import calls this
* class for every old script, so bookmarks, search engines and links in
* imported posts keep working. The ids stay the same during the import, so the
* translation only has to rename the scripts and their parameters.
*
* @copyright The iForum project
* @license GNU GPL v2, see LICENSE
* @package imforum
* @since 1.0
*/

class mod_imforum_LegacyUrl {

/** The scripts of iForum that have a counterpart */
public const SCRIPTS = ['index', 'viewforum', 'viewtopic', 'viewpost', 'viewall', 'rss'];

/**
* The page of imforum for an old script and its query, relative to the module folder
*
* @param array<string, mixed> $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<string, int|string> $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;
}
}
4 changes: 2 additions & 2 deletions src/icms_version.php
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
31 changes: 31 additions & 0 deletions stub/iforum/icms_version.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<?php
/**
* Stub for the old iForum module
*
* Installed in modules/iforum after the data has been imported into imforum. It
* holds no data and no templates: its scripts only send the old addresses on to
* imforum with a permanent redirect.
*
* @license GNU GPL v2, see LICENSE
* @package iforum
*/

defined('ICMS_ROOT_PATH') || die('ImpressCMS root path not defined');

$modversion = [
'name' => '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' => [],
];
18 changes: 18 additions & 0 deletions stub/iforum/index.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<?php
/**
* Old iForum address: permanent redirect to the same page of imforum
*
* @license GNU GPL v2, see LICENSE
* @package iforum
*/

include_once dirname(__DIR__, 2) . '/mainfile.php';
if (!is_dir(ICMS_ROOT_PATH . '/modules/imforum')) {
header('Location: ' . ICMS_URL . '/', true, 302);
exit;
}
include_once ICMS_ROOT_PATH . '/modules/imforum/include/common.php';
if (!class_exists('mod_imforum_LegacyUrl')) {
include_once ICMS_ROOT_PATH . '/modules/imforum/class/LegacyUrl.php';
}
mod_imforum_LegacyUrl::redirect('index');
18 changes: 18 additions & 0 deletions stub/iforum/rss.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<?php
/**
* Old iForum address: permanent redirect to the same page of imforum
*
* @license GNU GPL v2, see LICENSE
* @package iforum
*/

include_once dirname(__DIR__, 2) . '/mainfile.php';
if (!is_dir(ICMS_ROOT_PATH . '/modules/imforum')) {
header('Location: ' . ICMS_URL . '/', true, 302);
exit;
}
include_once ICMS_ROOT_PATH . '/modules/imforum/include/common.php';
if (!class_exists('mod_imforum_LegacyUrl')) {
include_once ICMS_ROOT_PATH . '/modules/imforum/class/LegacyUrl.php';
}
mod_imforum_LegacyUrl::redirect('rss');
18 changes: 18 additions & 0 deletions stub/iforum/viewall.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<?php
/**
* Old iForum address: permanent redirect to the same page of imforum
*
* @license GNU GPL v2, see LICENSE
* @package iforum
*/

include_once dirname(__DIR__, 2) . '/mainfile.php';
if (!is_dir(ICMS_ROOT_PATH . '/modules/imforum')) {
header('Location: ' . ICMS_URL . '/', true, 302);
exit;
}
include_once ICMS_ROOT_PATH . '/modules/imforum/include/common.php';
if (!class_exists('mod_imforum_LegacyUrl')) {
include_once ICMS_ROOT_PATH . '/modules/imforum/class/LegacyUrl.php';
}
mod_imforum_LegacyUrl::redirect('viewall');
18 changes: 18 additions & 0 deletions stub/iforum/viewforum.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<?php
/**
* Old iForum address: permanent redirect to the same page of imforum
*
* @license GNU GPL v2, see LICENSE
* @package iforum
*/

include_once dirname(__DIR__, 2) . '/mainfile.php';
if (!is_dir(ICMS_ROOT_PATH . '/modules/imforum')) {
header('Location: ' . ICMS_URL . '/', true, 302);
exit;
}
include_once ICMS_ROOT_PATH . '/modules/imforum/include/common.php';
if (!class_exists('mod_imforum_LegacyUrl')) {
include_once ICMS_ROOT_PATH . '/modules/imforum/class/LegacyUrl.php';
}
mod_imforum_LegacyUrl::redirect('viewforum');
18 changes: 18 additions & 0 deletions stub/iforum/viewpost.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<?php
/**
* Old iForum address: permanent redirect to the same page of imforum
*
* @license GNU GPL v2, see LICENSE
* @package iforum
*/

include_once dirname(__DIR__, 2) . '/mainfile.php';
if (!is_dir(ICMS_ROOT_PATH . '/modules/imforum')) {
header('Location: ' . ICMS_URL . '/', true, 302);
exit;
}
include_once ICMS_ROOT_PATH . '/modules/imforum/include/common.php';
if (!class_exists('mod_imforum_LegacyUrl')) {
include_once ICMS_ROOT_PATH . '/modules/imforum/class/LegacyUrl.php';
}
mod_imforum_LegacyUrl::redirect('viewpost');
18 changes: 18 additions & 0 deletions stub/iforum/viewtopic.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<?php
/**
* Old iForum address: permanent redirect to the same page of imforum
*
* @license GNU GPL v2, see LICENSE
* @package iforum
*/

include_once dirname(__DIR__, 2) . '/mainfile.php';
if (!is_dir(ICMS_ROOT_PATH . '/modules/imforum')) {
header('Location: ' . ICMS_URL . '/', true, 302);
exit;
}
include_once ICMS_ROOT_PATH . '/modules/imforum/include/common.php';
if (!class_exists('mod_imforum_LegacyUrl')) {
include_once ICMS_ROOT_PATH . '/modules/imforum/class/LegacyUrl.php';
}
mod_imforum_LegacyUrl::redirect('viewtopic');
Loading
Loading