Cross References

GitHub-style cross-references between discussions and posts for Flarum 2. Type #42 in any post to link the current discussion to discussion #42 — the target picks up a backlink, the target's author can be notified, and a sidebar widget surfaces every inbound reference.

Built as a more robust Flarum 2 successor to club-1/flarum-ext-cross-references: rename-safe rendering, visibility-aware backlinks, batched queries, and a references:N search filter — all wired through Flarum 2's first-party patterns.

---

What it does, at a glance

1. Inline references render as rich chips with the live discussion title

Type #42 in a post and it renders as a tappable chip showing the target discussion's current title — pulled fresh from the database on every render, so renames flow through automatically and you never read a stale title.

2. Target discussions get a backlink as a first-class event-post

When a post references another discussion, a small "Referenced from #X" event-post appears in the target's stream — slot-in to your existing moderation history, search index, and reply pipeline.

3. Every discussion gets an "inbound references" sidebar widget

A widget on the right-hand side of DiscussionPage lists the most recent inbound refs, with the source author and a relative timestamp. Click an item to jump to the referring discussion.

4. The target's author gets an in-app notification

The recipient sees the alert in their Flarum notification dropdown, with the source discussion title resolved live. Self-references (when you reference your own discussion) are silently skipped to avoid noise.

5. Every post header shows a copy-to-clipboard #N chip

So you always know which post number to use when typing #42/pN. Click the chip and the canonical cross-reference (#discussionId/pN) is copied to your clipboard, ready to paste into a reply.

---

Quick start

composer require ernestdefoe/cross-references
php flarum migrate
php flarum cache:clear

Then enable from the admin panel under Extensions → Cross References, grant the Use cross-references in posts permission to whichever groups should be allowed to type #42, and you're done — references start working immediately on new and edited posts.

---

Usage — how to reference a discussion or a specific post

Syntax cheat-sheet

Type this in your post	What renders	Where it points
#42	#42 — <Discussion Title>	discussion 42, top of the page
#42/p7	#42 — <Discussion Title> (post #7)	discussion 42, post number 7

Tip: every post header shows a clickable #N chip — click it to copy the canonical #discussionId/pN reference straight to your clipboard, so you never have to guess a post number.

| https://forum.example.com/d/42 | #42 — <Discussion Title> | discussion 42 (URL auto-shortened) | | https://forum.example.com/d/42-some-slug/7 | #42 — <Discussion Title> (post #7) | discussion 42, post 7 | | [click here](https://forum.example.com/d/42) | a regular markdown link "click here" | preserved as-is — Markdown wins |

The #N form is the canonical one. Pasted forum-discussion URLs get rewritten to #N at parse time before storage, so the database only ever sees a single representation. URLs you explicitly wrap in markdown brackets ([label](url)) are left alone — the extension assumes you meant the custom label intentionally.

A complete example

You're replying to a support discussion and want to link out to two related threads — a bug report and a specific post inside a roadmap discussion:

Write:

Thanks for the report! This looks like the same regression as #42, and the
fix is being planned in #58/p3. I'll close this as a duplicate once #58/p3
lands.

Renders as:

Thanks for the report! This looks like the same regression as #42 Login button stops responding on mobile, and the fix is being planned in #58 Q3 roadmap (post #3). I'll close this as a duplicate once #58 Q3 roadmap (post #3) lands.

The chips are clickable — they navigate to /d/42 and /d/58/3 respectively.

Meanwhile, in discussions #42 and #58:

• The bug report (#42) gets a new event-post that reads you referenced this from #137 (the support thread's ID).
• The roadmap (#58) gets the same event-post pointing back to #137.
• The author of #42 and the author of #58 each get an in-app notification alerting them that their discussion was referenced.
• The sidebar of both discussions now lists #137 as an inbound reference.

Visibility — references respect who can see what

References are visibility-scoped on every read path. If a viewer can't see the target (e.g., it's in a restricted tag or a private group), the chip renders as a muted #42 placeholder with no title leaked. Backlink event-posts inherit the target's normal visibility, so a backlink in a private thread doesn't leak the source thread's existence to non-members.

Viewer can see target?	Chip renders as
Yes	#42 — <Title> — full chip, clickable
No (private, restricted tag)	#42 (muted, CrossReference--hidden class)

The sidebar widget applies the same scope — inbound refs from sources you can't view simply don't appear.

Renames are automatic

Because titles are never persisted in the post content — only the discussion ID is — renaming a referenced discussion flows through to every chip on every render. No reindex, no chore:reparse, no cache invalidation needed. The next request gets the new title.

Searching for references

Use the references:N filter on the discussion list to find every discussion whose posts reference discussion #N:

filter[references]=42

Either as a URL parameter on /api/discussions or via the standard search input if you've wired it (works alongside any other filter):

filter[references]=42&filter[tag]=support

Negation works too: -references:42 excludes them.

---

Admin settings

Under Admin → Extensions → Cross References, three toggles:

Setting	Default	Effect
Show inline references in posts	on	Render #42 / pasted-URL refs as rich chips. Turn off to fall back to raw #42 text.
Create backlink event-posts in target discussions	on	Insert "Referenced from #X" event-posts in the target. Disable for forums that prefer quiet target threads.
Notify the target discussion's author	on	Send an in-app alert when someone references the recipient's discussion. The actor never notifies themselves.

And one permission:

• Use cross-references in posts — gate #42 rendering at the group level. Useful for forums that want references to work only for trusted members.

---

Architecture

What gets stored

A single companion table cross_references with a row per (source_post, target_discussion, target_post?) tuple. Unique constraint on that tuple gives storage-layer dedupe — re-saving a post that mentions #42 three times produces one row.

cross_references
  id                     bigint PK
  source_post_id         FK posts.id     ON DELETE CASCADE
  source_discussion_id   FK discussions.id
  target_discussion_id   FK discussions.id  ON DELETE CASCADE
  target_post_id         FK posts.id (nullable — null = whole-discussion ref)
  created_at             timestamp
  UNIQUE (source_post_id, target_discussion_id, target_post_id)
  INDEX  (target_discussion_id)   -- inbound-refs lookup
  INDEX  (source_discussion_id)   -- outbound-refs lookup

The table follows Flarum 2's companion-table convention — no columns added to posts or discussions (CLAUDE.md §45).

How rendering works

1. Parse-time: The s9e/TextFormatter Preg plugin matches \B#(\d+)\b and \B#(\d+)/p(\d+)\b and emits <CROSSREF id="42" postnum="7"/> tags into the stored XML. Pasted forum URLs are pre-rewritten to the #N form before the parser sees them.
2. Pre-render: a single batched Discussion::whereIn('id', $ids) ->whereVisibleTo($actor) query resolves every referenced discussion's title in one round-trip. Titles + visibility flags get injected onto each <CROSSREF> tag as attributes.
3. Render: the XSL template uses the title attribute when set, falling back to the CrossReference--hidden placeholder when visibility denies the read.

No titles are persisted in post content. No per-post N+1 query. One DB call per page render, regardless of how many cross-references are in the visible posts.

Bidirectional backlinks + notifications

The Posted / Revised event listener extracts CROSSREF tags from the post's parsed XML, diffs against the existing cross_references rows for that post, then:

• Inserts rows for new references; deletes rows for removed ones.
• For each new ref, creates a CrossReferenceEventPost (extending Flarum's AbstractEventPost) in the target discussion. Lives alongside core event-posts like "renamed" or "locked" — participates in moderation, search, and the standard reply pipeline.
• Optionally dispatches a DiscussionReferencedBlueprint notification to the target's author via the alert channel.

Self-references are silently dropped. The listener is wrapped in try/catch with PSR-3 logging so a cross-ref bug can never block a post save (CLAUDE.md §41).

API endpoint

GET /api/discussions/{id}/cross-references

Returns the inbound references for a discussion, with each row visibility-scoped against the requesting actor and eager-loaded with the source discussion title + first-post author. Capped at 50 rows — the response includes a meta.capped50 boolean so a future "view all" page can fall back to a paginated source.

{
  "data": [
    {
      "id": 1,
      "sourceDiscussionId": 6,
      "sourcePostId": 4,
      "targetPostId": null,
      "createdAt": "2026-05-17T13:59:39+00:00",
      "source": {
        "discussionTitle": "Cross-ref smoke test",
        "discussionSlug": "cross-ref-smoke-test",
        "author": {
          "id": 2,
          "displayName": "tester",
          "username": "tester",
          "avatarUrl": null
        }
      }
    }
  ],
  "meta": { "count": 1, "capped50": false }
}

Search filter

Registered via Extend\SearchDriver(DatabaseSearchDriver) ->addFilter(DiscussionSearcher, ReferencesFilter). The value is cast to (int) before reaching SQL — defeats the §10 wildcard / sort-allowlist trap surface; the gambit accepts numeric ids only, never strings.

---

Comparison vs. club-1/flarum-ext-cross-references

Concern	club-1/cross-references	ernestdefoe/cross-references
Flarum version	1.x	2.x
Discussion title in chip	Baked into post content at save	Resolved live from DB on every render
Behavior on target rename	Requires chore:reparse to refresh stored chips	Automatic — chips read current title
Behavior on target delete	Plain link to nothing	Chip renders as muted #N placeholder
Visibility-aware	No (leaks restricted titles)	Yes — whereVisibleTo($actor) everywhere
Backlink mechanism	Event post	Event post (first-class, extends AbstractEventPost)
Notifications to target author	No	Yes — AlertableInterface blueprint
Inbound-refs sidebar widget	No	Yes
Search filter (references:N)	No	Yes
Per-post listener failures block post save	Possible	Caught + logged, never blocks save
Dedupe	None	Unique index at storage layer

---

Architecture notes (for extension authors reading this for reference)

This extension was built against the Flarum 2 security/structure playbook — relevant sections:

• §5 — whereVisibleTo($actor) applied at every read path (API endpoint, render-time enrichment, search filter sub-query). Inbound-refs sidebar filters source visibility per actor before payload assembly.
• §19 — getData() carries IDs only; titles re-resolved from the subject relation at render time so a target that turns private later doesn't leak its old title via a stale notification.
• §26 — Migration uses Flarum\Database\Migration::createTableIfNotExists with explicit cascadeOnDelete FKs and a composite unique index for storage-layer dedupe.
• §38 — Single batched query per render to resolve all titles for a post; one batched visibility check for the sidebar. No N+1.
• §41 — Psr\Log\LoggerInterface injected in the listener + controller; try/catch wraps both so a ref bug can never block a post save.
• §43 — composer.json constrained to "flarum/core": "^2.0"; no ^1.0 fallback, since v2-only Endpoint/Schema classes are imported.
• §45 — Companion cross_references table; no columns added to core posts/discussions/users.
• §46 — DiscussionReferencedBlueprint has a typed constructor + TYPE class constant + getSubjectModel() returns Discussion::class, so the polymorphic subject relationship resolves cleanly via typeForModel().

---

Contributing

Pull requests welcome. For non-trivial changes, please open an issue first so we can discuss the approach.

• composer require ernestdefoe/cross-references:dev-main (or path repo) in your local Flarum to develop against.
• cd js && npm install && npm run dev watches and rebuilds the JS bundle on every change.
• php flarum cache:clear after PHP changes.

License

MIT © Ernestdefoe