Redesign Topic Prefixes into Tagging system

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+### 2.0.0-dev - TBD
+
+- Renamed phpBB Topic Prefixes to phpBB Topic Tags and replaced single text prefixes embedded in titles with relational topic metadata.
+- Added multiple color-coded tags per topic with automatic badge text contrast and badges throughout forum, topic, MCP, and search displays.
+- Added centralized ACP management for tag text, color, order, status, and availability across multiple forums.
+- Redesigned ACP management with a responsive tag catalog, sticky editor, searchable forum assignments, drag-and-drop ordering, and AJAX updates.
+- Added accessible tag selection when creating topics or editing their first posts.
+- Added clickable filters that combine multiple tags using AND matching in forum lists, category Active Topics, and SQL-backed keyword or author search results shown as topics or posts.
+- Added opt-in, permission-filtered tag autocomplete to advanced search, including tag-only topic search and all/any matching.
+- Preserved tags through topic moves, splits, forks, and merges, including tags retained after moving into forums where they are unavailable for new assignments.
+- Added a safe, restartable upgrade that converts legacy prefixes and assignments into tags while removing matching prefix text from topic titles and first-post subjects.
+- Added automatic splitting of complete adjacent bracket sequences and consolidation of duplicate legacy definitions with matching names and enabled states, while preserving malformed formats and same-name definitions with conflicting states.
+- Required legacy upgrades to run with the board disabled and directed administrators to back up the database first.
+- Added an interactive CLI for splitting tags into multiple separate tags or merging one tag into another.
+- Raised minimum requirements to phpBB 3.3.19 and PHP 7.2.
+- Note: implementations for showing tags on UCP main page, bookmarks, and subscriptions will take effect after phpBB adds new proposed events (targeted for 3.3.19).
+
 ### 1.0.2 - 2025-12-17
 
 - Strengthened compatibility with both phpBB3 and phpBB4-alpha-1.

README.md

@@ -1,19 +1,82 @@
-# phpBB Topic Prefixes
+# phpBB Topic Tags
 
-This is the repository for the development of the Topic Prefixes phpBB extension.
+This is the repository for development of phpBB Topic Tags, formerly named Topic Prefixes.
 
 [![Build Status](https://github.com/phpbb-extensions/topicprefixes/actions/workflows/tests.yml/badge.svg)](https://github.com/phpbb-extensions/topicprefixes/actions)
 [![codecov](https://codecov.io/gh/phpbb-extensions/topicprefixes/branch/master/graph/badge.svg?token=Dc0GWOeQWj)](https://codecov.io/gh/phpbb-extensions/topicprefixes)
 
-The phpBB Topic Prefixes extension allows phpBB board administrators to create topic prefix tags that users can easily add to their topic titles. Features include:
+The phpBB Topic Tags extension provides administrator-curated topic tags. Tags are structured topic metadata and are displayed separately from topic titles as colored badges. Features include:
 
-- Create unique and unlimited prefixes for each forum in your phpBB board.
-- Admins can sort, enable and disable prefix tags.
-- Users will see a topic prefix menu when creating a new topic in a forum that uses topic prefixes.
-- Topic prefixes can easily be changed when a user is editing their original first post.
-- Because the topic prefix is added directly to the topic title, if an admin disables or deletes a topic prefix, existing topic titles using the deleted prefix will not be changed.
+- Create, edit, order, enable, disable, and color topic tags.
+- Make each tag available in one or more forums.
+- Assign multiple tags while creating a topic or editing its first post.
+- Display readable colored badges in topic lists, topic pages, and search results.
+- Filter forum and category Active Topics lists by one or more tags using AND semantics.
+- Optionally enable tag search in ACP > General > Board features, adding a permission-filtered autocomplete to advanced search with all/any matching and tag-only topic results.
+- Filter keyword and author search results shown as topics or posts when using phpBB native, MySQL fulltext, or PostgreSQL search. Sphinx supports tag-only search but not combined tag and text/author search.
+- Upgrade existing title prefixes safely into relational tag assignments.
 - This is the same extension currently in use at phpbb.com in the Extensions and Styles in development forums.
 
+## Upgrading from 1.x
+
+Before enabling version 2, make a full database backup and disable the board in
+General > Board settings. The extension blocks a legacy upgrade while the board
+is enabled.
+
+Migration splits complete adjacent bracket sequences such as `[3.3][DEV]` into
+separate tags. Legacy prefixes duplicated within or across multiple forums are
+consolidated into one tag available in each applicable forum when their decoded
+names and enabled states match. Other combined formats and same-name definitions with
+different enabled states remain separate. This upgrade is one-way; restore the
+pre-upgrade database backup to undo it.
+
+## Repair tools
+
+Before applying any repair, make a current database backup and disable the
+board. Each tool shows a preview and asks for confirmation before changing
+anything.
+
+### Repair tags
+
+Use this command to split a combined tag into separate tags or merge one tag
+into another:
+
+```shell
+php bin/phpbbcli.php topicprefixes:repair-tags
+```
+
+To repair a specific tag, add `--tag-id=ID`.
+
+### Repair topics
+
+Use this command to repair missing topic tags or old prefixes, usually after
+upgrading from version 1 to version 2:
+
+```shell
+php bin/phpbbcli.php topicprefixes:repair-topics
+```
+
+Choose the action that matches the problem:
+
+- **Recover missing topic tags:** use when a topic still shows its old prefix
+  and has no tag.
+- **Clean leftover topic titles:** use when tags migrated correctly but old
+  prefix text remains in topic titles.
+- **Clean historical reply subjects:** optionally remove old prefixes from
+  replies. Reply subjects are normally kept as part of the discussion history.
+
+Missing-tag candidates are grouped by forum and inferred tags. You can review
+each group in pages of 20, stop previewing at any page, then approve or skip the
+whole group. The confirmation reports how many candidates were and were not
+previewed. Each completed repair action creates one administrator-log summary.
+
+For title or reply cleanup, enter the old prefix exactly as shown and select the
+forum to repair. If post subjects change, rebuild the search index in ACP >
+Maintenance > Search index.
+
+Some missing information cannot be recovered from the current database. If the
+tool cannot identify the old tag, use a pre-upgrade backup to determine it.
+
 📦 [Download](https://www.phpbb.com/customise/db/extension/topicprefixes/) the latest release of this extension.
 
 🐞 [Report bugs](https://github.com/phpbb-extensions/topicprefixes/issues) to our Issue Tracker.

acp/topic_prefixes_info.php

@@ -10,9 +10,17 @@
 
 namespace phpbb\topicprefixes\acp;
 
+/**
+ * Describe Topic Prefixes ACP module registration.
+ */
 class topic_prefixes_info
 {
-	public function module()
+	/**
+	 * Return ACP module metadata.
+	 *
+	 * @return array ACP module definition
+	 */
+	public function module(): array
 	{
 		return [
 			'filename'	=> '\phpbb\topicprefixes\acp\topic_prefixes_module',

acp/topic_prefixes_module.php

@@ -11,29 +11,34 @@
 namespace phpbb\topicprefixes\acp;
 
 /**
- * Class topic_prefixes_module
+ * Dispatch Topic Prefixes ACP requests to the administrator controller.
  */
 class topic_prefixes_module
 {
-	/** @var string */
+	/** @var string Module action URL */
 	public $u_action;
+
+	/** @var string Template name */
 	public $tpl_name;
+
+	/** @var string Page title language key */
 	public $page_title;
 
 	/**
-	 * Main ACP module
+	 * Dispatch the current ACP request.
 	 *
-	 * @throws \Exception
+	 * @return void
+	 * @throws \Exception When controller dispatch fails
 	 */
-	public function main()
+	public function main(): void
 	{
 		global $phpbb_container;
 
 		$lang = $phpbb_container->get('language');
 		$lang->add_lang('acp/forums');
 		$lang->add_lang('acp_topic_prefixes', 'phpbb/topicprefixes');
 		$this->tpl_name   = 'acp_topic_prefixes';
-		$this->page_title = 'TOPIC_PREFIXES';
+		$this->page_title = 'TOPIC_TAGS';
 
 		$admin_controller = $phpbb_container->get('phpbb.topicprefixes.admin_controller');
 		$admin_controller->set_u_action($this->u_action)->main();