Download the PHP package ernestdefoe/cross-references without Composer

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

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

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:

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.

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:

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

Negation works too: -references:42 excludes them.

Admin settings

Under Admin → Extensions → Cross References, three toggles:

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.

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

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.

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

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.

Support

Questions, bug reports, and feature requests:

• Support forum: https://ernestdefoe.online
• Issues: https://github.com/ernestdefoe/cross-references/issues

License

MIT © Ernestdefoe