omnibase/forum

Installation

Requirements

• PHP 8.2 or later;
• doctrine/orm 2.15 or 3;
• omnisense/omnibase 3.0 or 4.0, omnibridge/symfony 1.x, omnibase/admin;
• league/commonmark 2.4 or later;
• Symfony 6, 7 or 8 (config, dependency-injection, form, http-kernel, security-bundle);
• an App\Entity\User class: authors, last posters, deleters and voters are that entity.

omnibase/admin is required, not optional: omnisense/omnibase walks every class of a bundle's src/ when it builds its App\ aliases, so CRUD controllers extending an admin class that is not installed would break the application.

The bundle

composer require omnibase/forum:dev-main

// config/bundles.php
Base\Forum\ForumBundle::class => ['all' => true],

The routes

# config/routes.yaml
forum_controller:
    resource: "@ForumBundle/src/Controller/Client"
    type: attribute
    prefix: /

The order page of the back office, /admin/bbs/ordre, is in src/Controller/Admin; a site that wants it imports that directory too (the CRUD controllers beside it carry no route attribute and add nothing):

forum_admin_controller:
    resource: "@ForumBundle/src/Controller/Admin"
    type: attribute
    prefix: /

The configuration

Every key is optional (Configuration reference):

# config/packages/forum.yaml
forum:
    topics_per_page: 20
    posts_per_page: 10
    flood_interval: 15
    hot_threshold: 25
    active_hours: 72
    moderator_role: ROLE_ADMIN
    admin_role: ROLE_SUPER_ADMIN

The moderation rule reads the role hierarchy of security.yaml (Who may do what).

The schema and the assets

bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate   # forum_category, forum_topic, forum_post, forum_poll, forum_poll_vote
bin/console assets:install                # public/bundles/forum/css, public/bundles/forum/js

The layout

Every forum page extends @Forum/client/layout.html.twig, which extends the site's layout1.html.twig and fills its title, stylesheets and content blocks (Templates and Twig).

Overriding the entities

The bundle maps Base\Forum\Entity\* to App\Entity\Forum\* and Base\Forum\Repository\* to App\Repository\Forum\* (omnisense/omnibase's App-wins aliasing): an App\Entity\Forum\Topic extending Base\Forum\Entity\Topic takes over.

The demo

The repository holds a demo application under example/app/ (bundles, routes, Doctrine, security, forum.yaml, a layout1.html.twig) and a Dockerfile that builds it with SQLite; its first page seeds two members, a group with a public and a staff-only board, three tags and a topic with a reply.

Concepts

Groups and boards

Base\Forum\Entity\Category is a two-level tree. A category without a parent is a group (isGroup()): it holds boards and no topics. A category with a parent is a board (isBoard()): it holds topics.

CategoryRepository::findTree() returns the groups with their boards, findBoards() the boards, findOneBySlug() one category.

Topics

Base\Forum\Entity\Topic extends omnisense/omnibase's Base\Entity\Thread (discriminator forum_topic). From the thread it has its owners (the author), title (translatable), slug, tags, followers, likes, state and publication date. It adds:

addPost() updates replies, lastPostAt and lastPoster. setAuthor() changes the owner and the opening post's author together. Views are counted with a direct UPDATE, so a reader does not touch the thread's updatedAt.

Scheduled topics

A topic is out the moment it is written. schedule($at) gives it an hour to come out at: the publication date becomes that hour when it is in the future, now otherwise, and a topic nobody has answered moves its last activity there too, so it comes into the lists at its hour. isUpcoming() is true until then.

No command has to run: every list goes through TopicRepository::whereOut(), which keeps the topics whose publication date is null or past. Until its hour, an upcoming topic is its authors' and its board's moderators' only; nobody replies to it; anyone else gets a 404 on its address (Who may do what).

Posts

Base\Forum\Entity\Post holds the Markdown content, its author, the message it answers (replyTo), its edit count and the hour of its last edit (markEdited(), when its author edits it), and a soft delete (deletedAt, deletedBy): delete() keeps the post's place and number, restore() brings it back. getNumber() is its 1-based position in the topic, isFirst() says whether it is the opening post, getShownAt() is the hour shown on it (for the opening post of a scheduled topic, the hour the topic came out).

Deleting the opening post deletes the topic.

Polls

Base\Forum\Entity\Poll belongs to one topic: a question (200 characters), 2 to 10 answers (MIN_OPTIONS, MAX_OPTIONS, each cut at 120 characters) and maxChoices (1, a single answer; more, up to that many, never more than there are answers). PollVote records one answer of one member; a unique key on poll, member and answer keeps a member from counting twice. A poll is open while its topic is not locked (isOpen()); getCounts() gives the votes per answer, getTotal() the voters, getChoicesOf($user) what a member chose.

Tags

The tags are omnisense/omnibase's Tag, shared with every thread. TopicRepository::findTagUsage() returns the tag cloud: the tags in use on topics that are out, highest priority first (the order page sets it), then the most used.

Who may do what

The voter

Base\Forum\Security\ForumVoter answers seven attributes. Its subject is a category, a topic or a post; a topic and a post are judged by their board.

An upcoming topic (scheduled, not out yet) changes three answers: nobody replies to it, and anyone who is neither one of its owners nor a moderator of its board is refused everything on it and on its posts, FORUM_READ included.

Who moderates a board

ForumVoter::moderates($roles, $category) reads the role hierarchy of the firewall (security.role_hierarchy):

• the admin role (forum.admin_role, ROLE_SUPER_ADMIN by default) moderates every board;
• the moderator role (forum.moderator_role, ROLE_ADMIN by default) moderates the open boards, and the boards kept for a role it stands above;
• a board kept for the moderator role's own rank is the admins' to moderate: its moderators read it, the admins keep order there;
• a board kept for a role outside the moderator's branch, the moderator cannot even read;
• announcement boards are the admin role's alone.

With this hierarchy:

# config/packages/security.yaml
security:
    role_hierarchy:
        ROLE_HELPER: ROLE_USER
        ROLE_ADMIN: ROLE_HELPER
        ROLE_SUPER_ADMIN: ROLE_ADMIN

a ROLE_ADMIN member moderates the open boards and a board kept for ROLE_HELPER; a board kept for ROLE_ADMIN is moderated by ROLE_SUPER_ADMIN only.

What the controllers check

The moderators are exempt from the flood interval.

In templates

{% if is_granted('FORUM_POST', category) %}
    <a href="{{ path('forum_topic_new', {category: category.slug}) }}">{{ '@forum.topic.new'|trans }}</a>
{% endif %}

Lists outside a board

The index's feed, the tag page (/bbs/t/{slug}), the search (/bbs/recherche) and the sitemap list only the topics of the boards the reader may read (FORUM_READ): a board kept for a role never shows its titles, its name or its last posters to someone without it. TopicRepository::createLatestQuery(), createTrendingQuery(), createTagQuery() and createSearchQuery() take the readable boards' ids (null: every board), the controller passing those FORUM_READ grants.

The pages

Routes

forum_category_new and forum_topic_new carry a route priority of 5, so /bbs/{slug} does not take nouveau-forum or nouveau for a topic. Likes and follows go through omnisense/omnibase's thread API (/api/thread/{slug}/like, unlike, follow, unfollow).

The index

/bbs has two views:

• classic, the board list grouped under its groups, with each board's topics and replies, its last message (who, when, in which topic), its folder badge, and a list of the latest topics below (@Forum/client/index.html.twig);
• feed, a flat list of the latest topics with the two latest announcements and up to six pinned topics on top (@Forum/client/index_fil.html.twig).

The feed has two orders: recent (the latest activity) and popular (among the topics that moved in the last 30 days, the most replies, then the most views). Both list only the boards the reader may read, and topics that are out.

Display choices

The reader's choices are kept in a cookie for a year, never in the address:

Each button is a small POST form to forum_display with the choice and back, the page to return to. An unknown name or value is ignored; back must be a path on the site (it starts with /, not //), otherwise the index.

A board, a group, a tag, the search

A group's page lists its boards. A board's page lists its topics, pinned first, then by last activity; its moderators also see its upcoming topics, marked. A tag's page lists the topics carrying the tag. The search needs at least three characters and matches, without case, a topic's title or the content of any of its posts (a LIKE; no index).

A topic

A topic's page shows its posts, posts_per_page at a time, the reply form for those who may reply, the poll, the previous and next topics of its board, and a "jump to" list of the boards the reader may read. An outline of the whole topic is built from one query: each post's parent (the message it answers, or the trunk), its branch, level and depth, its number and page, and how many posts answer it; the timeline script and the "in reply to" lines read it.

Infinite lists

A board, a tag, the search, the feed and a topic load their next page as the reader scrolls (forum-feed.js, forum-thread.js): the script asks the same address with the header X-Forum-Stream and receives the rows alone. The responses carry Vary: X-Forum-Stream, and a page loaded that way does not count a view.

The sitemap

Base\Forum\EventListener\SitemapListener adds, on omnisense/omnibase's SitemapEvent::BUILD, every board without a requiredRole (its update date) and the latest topics of those boards that are out, up to 5,000 (MAX_TOPICS), each with the date of its last activity.

Writing, replying, voting

Opening a topic

/bbs/nouveau/{category} opens a topic (Base\Forum\Form\Type\TopicType, model Base\Forum\Form\Model\TopicModel):

When the page is not opened from a board, the board list offers only the boards the writer may post in (FORUM_POST); with none, the page flashes @forum.aside.cannot_post and returns to the index.

?depuis=<post id> opens a topic out of a message: the new topic starts on the same board, its content prefilled with a link back to that message (@forum.topic.linked_opening).

On submit, in order: a scheduling refused for that board puts an error on publishedAt; a board the writer may not post in flashes @forum.flash.board_locked; a post sent within the flood interval flashes @forum.flash.flood with the seconds to wait. Otherwise the topic, its opening post and its poll are saved, and the page redirects to the topic, flashing @forum.flash.topic_created or, for an upcoming topic, @forum.flash.topic_scheduled with its hour.

Replying

The reply form (Base\Forum\Form\Type\PostType, 2 to 20,000 characters) is on the topic's page for those who may reply, and posts to /bbs/{slug}/repondre. ?quote=<post id> prefills it with that post quoted; ?reply=<post id> links the reply to that post without quoting it. The link is sent as reply_to and kept when the post belongs to the same topic. After the reply, the page redirects to the new post, on its page; a refusal or an invalid form flashes its message and returns to the topic.

The flood interval

A member waits forum.flood_interval seconds (15 by default) after their last post before posting again, a topic or a reply. 0 turns it off; moderators are never held.

Editing

/bbs/{slug}/modifier edits a topic's title and tags (the opening post is edited as a post). A moderator of the topic's board can also move it to another board they moderate; while the topic is upcoming, those who may schedule there can move its hour; the forum admin can change whose name it is under.

/bbs/message/{id}/modifier edits a post. When its author edits it, the post records the hour and counts the edit; a moderator's edit does not.

Moderating and deleting

The moderation buttons post to /bbs/{slug}/moderer/{action} with a CSRF token (forum_moderate_<topic id>): pin, unpin, lock, unlock, and delete, which an author may also do on their own topic. Deleting a topic returns to its board.

/bbs/message/{id}/supprimer (CSRF token forum_post_<post id>) deletes a post softly: it keeps its place and number, shown as deleted. The same button on a deleted post restores it, for a moderator. Deleting the opening post deletes the topic.

Voting

A poll's form posts to /bbs/{slug}/voter with a CSRF token (forum_vote_<poll id>) and choice (one answer) or choice[] (several). The vote is refused, with a flash, when the topic is locked (@forum.poll.flash.closed), when no valid answer is sent (@forum.poll.flash.no_choice), when more answers than allowed are sent (@forum.poll.flash.too_many), or when the member has voted (@forum.poll.flash.already). A vote is final, and its answers are saved together: a second click arriving with the first meets the unique key and is answered as already voted.

Opening a board from the site

/bbs/nouveau-forum (FORUM_ADMIN) opens a board in the group named by ?dans=<group slug>, or a new group without it (Base\Forum\Form\Type\CategoryType: title, group, description, announcement, polls). It is placed last among its siblings (ten past the highest position), and the page redirects to it, flashing @forum.flash.board_created or @forum.flash.group_created. The order page moves it; the back office edits the rest.

Markdown

The renderer

Base\Forum\Service\MarkdownRenderer renders a post with league/commonmark: CommonMark, GitHub flavouring (tables, task lists, strikethrough), autolinks. Raw HTML is escaped (html_input: escape, and the disallowed raw HTML extension), javascript: links are dropped (allow_unsafe_links: false), nesting stops at 20 levels, and a single line break becomes <br>.

Two forum habits are added:

• >>12, at a word boundary, becomes a link to #post-12, the anchor of post 12 of the same topic; inside code it stays as typed;
• @name (2 to 32 letters, digits, _ or -) becomes a link to the member's profile when the site has a route named user_profileByUsername (with a username parameter); inside code, a link or a tag it stays as typed.

An example

use Base\Forum\Service\MarkdownRenderer;

$markdown = new MarkdownRenderer();
$post = "As >>2 said, see [the docs](javascript:alert(1)) and <script>x()</script>.\n\n- [x] done\n- ~~old~~";
echo $markdown->render($post);
echo "---\n", $markdown->excerpt($post, 40), "\n---\n";
echo $markdown->quote("First line\nSecond line", 'anna');

Its output, run in omnisense/omnibase-harness (no router, so no mention links):

<p>As <a href="#post-2">&gt;&gt;2</a> said, see <a>the docs</a> and &lt;script&gt;x()&lt;/script&gt;.</p>
<ul>
<li><input checked="" disabled="" type="checkbox"> done</li>
<li><del>old</del></li>
</ul>
---
As >>2 said, see the docs and <script>x(…
---
> **@anna** a écrit :
> First line
> Second line

The excerpt decodes the entities after removing the tags, so the escaped <script> comes back as text: it is plain text, to be printed escaped (the forum_excerpt filter is not marked safe, so Twig escapes it).

quote() writes the author's line in the reader's language (reply.quote_wrote of the forum domain: "@author wrote:", "@author a écrit :"); built without a translator, in English.

In Twig

{{ post.content|forum_markdown }}       {# safe HTML #}
{{ topic.firstPost.content|forum_excerpt(120) }}
{{ forum_quote(post.content, post.author) }}

Templates and Twig

The layout

@Forum/client/layout.html.twig extends the site's layout1.html.twig. It fills title (the page's forum_title block, else the index's title), stylesheets (bundles/forum/css/forum.css) and content, in which it draws the forum's header, its pages and its side column. A page of the forum fills its own blocks:

The host's layout needs the title, stylesheets and content blocks.

Override points

A site overrides any template in templates/bundles/ForumBundle/. The two meant for it:

• client/_banner.html.twig, the banner above the forum;
• client/_avatar.html.twig, how a member is pictured.

The other partials (_topic_row, _post, _member, _folder, _badge, _legend, _pager, topic/_poll...) can be overridden the same way.

Scripts and stylesheets

After assets:install, under bundles/forum/:

Twig filters and functions

A topic's badge follows this precedence: an announcement (a topic of an announcement board, announce), a post-it (sticky), a locked topic (lock), a popular one (hot), then the plain folder (default); the last three take their awake art (new_lock, new_hot, new) when the topic has moved within active_hours. A board's badge reads the same way after its latest message: announce, lock, hot when it holds a popular topic, default; a board kept for a role says so in its title. "Awake" means recent activity, not unread: the forum keeps no read marker per member.

Translations

The domain forum, in English and French (ICU format), holds every text of the pages, the forms, the flashes and the back office; the templates call its keys as '@forum.<key>'|trans. A site overrides a message in its own translations/forum+intl-icu.<locale>.yaml.

The back office

The screens are loaded when omnibase/admin is installed (its Base\Admin\Controller\AbstractCrudController exists).

Categories

Base\Forum\Controller\Admin\Crud\CategoryCrudController edits groups and boards: title, slug (following the title), parent (none for a group), position, locked, announcement, polls, icon, colour, the role a reader needs (requiredRole, chosen among the site's roles; empty, everyone reads) and description. Filters: parent, locked.

Topics

Base\Forum\Controller\Admin\Crud\TopicCrudController edits a topic's title (a translation field), slug, board, tags, pin and lock; the index shows its views and replies. Filters: board, pinned, locked. Posts are edited on the site.

The two CRUD screens carry no #[OpenToAdmins]: their writes follow omnibase/admin's default.

The order page

/admin/bbs/ordre (forum_admin_order, ROLE_ADMIN; Base\Forum\Controller\Admin\OrderController) orders the whole forum on one screen: the groups, the boards in each group (a board can change group there), and the tags of the tag cloud. It posts order[groups][], order[boards][<group id>][] and order[tags][] with a CSRF token (forum_admin_order) and flashes admin.order.saved (domain forum).

Groups and boards are numbered 10, 20, 30..., so a board added later can be slotted between two without renumbering. A board stays a board and a group a group: only a board's parent changes. Tags go the other way: the first one gets the highest priority, which the tag cloud reads first.

Its route lives beside the CRUD controllers, in src/Controller/Admin, which a site imports (Installation).

The dashboard

yield MenuItem::linkToCrud(\Base\Forum\Entity\Category::class, 'Forums', 'fa-solid fa-comments');
yield MenuItem::linkToCrud(\Base\Forum\Entity\Topic::class, 'Topics', 'fa-solid fa-comment-dots');
yield MenuItem::linkToRoute('forum_admin_order', [], 'Order', 'fa-solid fa-sort');

The categories screen labels the polls field in the reader's language (form.board_polls).

Configuration reference

The forum tree

Dumped with Symfony's YamlReferenceDumper from Base\Forum\DependencyInjection\ForumConfiguration:

forum:

    # Topics listed per page in a category, a tag or the search.
    topics_per_page:      20

    # Posts shown per page inside a topic.
    posts_per_page:       10

    # Seconds a member must wait between two posts (phpBB called it flood_interval).
    flood_interval:       15

    # Replies from which a topic is flagged "hot".
    hot_threshold:        25

    # A board or topic with a message this recent is awake: its folder badge shows the "new" art instead of the sleeping "zzz".
    active_hours:         72
    title_max_length:     120
    content_max_length:   20000

    # Role allowed to pin, lock, move and delete any topic or post.
    moderator_role:       ROLE_ADMIN

    # Role allowed to open new boards and groups from the site itself (the back office has its own CRUD).
    admin_role:           ROLE_SUPER_ADMIN

Parameters

Each key is a container parameter: %forum.topics_per_page%, %forum.posts_per_page%, %forum.flood_interval%, %forum.hot_threshold%, %forum.active_hours%, %forum.title_max_length%, %forum.content_max_length%, %forum.moderator_role%, %forum.admin_role%.

Services

config/services.php autowires and autoconfigures everything under Base\Forum\ except the DI classes, the entities and the bundle class; the client controllers are tagged as controllers; the admin controllers are loaded when omnibase/admin is installed.

TopicRepository extends omnisense/omnibase's ThreadRepository (a Thread subclass needs its hierarchy trait), not ServiceEntityRepository.

Testing

Running the suite

From the package's checkout, with its dev dependencies:

vendor/bin/phpunit

phpunit.xml.dist boots tests/bootstrap.php, which registers the test namespace itself, so the same suite runs from inside a host application:

php vendor/bin/phpunit -c vendor/omnibase/forum/phpunit.xml.dist

In omnisense/omnibase-harness, mounting the checkout in place of the installed package:

docker run --rm --network none \
    -v "$PWD":/srv/demo/vendor/omnibase/forum:ro \
    omnisense/omnibase-harness:latest test forum

On this checkout, in the harness:

OK (28 tests, 59 assertions)

What the tests check

The voter, the controllers and the repositories have no test of their own.