SEO for Flarum 2
SEO meta tags, OpenGraph, Twitter Cards, JSON-LD structured data, a
bundled sitemap.xml generator, and search-console verification for
Flarum 2 — a maintained, v2-compatible continuation of
v17development/flarum-seo.
What's different from the upstream
The upstream extension targets Flarum 1.x and the partial Flarum 2 port
in v17development/flarum-seo left the API layer broken — it won't
even boot on Flarum 2 because four core classes (AbstractSerializer,
AbstractListController, AbstractShowController, AbstractDeleteController,
BasicDiscussionSerializer, ForumSerializer) were removed when the
core API was rewritten around Resource + Endpoint + Schema.
This fork:
- Boots and runs on Flarum 2.x. Full v2-API migration: the v1
serializer + 4 controllers became one SeoMetaResource with declarative
Endpoint::make() + Schema\* fields + writable allowlist. v1
ApiSerializer + ApiController extenders replaced with
ApiResource(...)->fields() callbacks mounting fields onto
DiscussionResource and ForumResource. Eager-load via
endpoint(...)->eagerLoad('seoMeta') to prevent N+1 on the discussion list.
- Migration bug fix. Upstream's
2023_02_01_create_seo_meta_table.php used
$table->string('object_type', 65535) which silently coerces to
MEDIUMTEXT and crashes the subsequent unique-index migration with
"BLOB/TEXT column used in key specification without a key length".
Reduced to varchar(60) so the unique index lands on first run.
- Bundled
sitemap.xml generator. Auto-detects fof/sitemap — if
installed, our controller 404s and defers to fof's. Otherwise generates
a single-file sitemap (capped at 50k URLs per the protocol limit) with
<lastmod> from last_posted_at, <changefreq> derived from
posting recency (hourly→yearly), and <priority> weighted by
comment count + recency. Visibility-scoped to Guest so restricted
tags / private groups never leak into the public sitemap. 6-hour
cache via the framework cache.
- Search-console verification meta tags. Four admin-configurable
settings: Google Search Console, Bing Webmaster, Yandex Webmaster,
Pinterest. Tokens are charset-restricted before interpolation so an
admin can't (intentionally or by typo) inject markup into the head.
Defensive try/catch around the injector so a verification-tag bug
can never block a page render.
robots.txt always references the sitemap. Upstream only added
the Sitemap: directive when fof-sitemap was enabled. Since we
now always serve a sitemap (ours or theirs), the reference is
unconditional.- Hardened
UploadSocialMediaImageController. Full §11 upload
pipeline: size cap (4 MB), extension allowlist (png/jpg/jpeg/webp),
finfo-based MIME re-detection, server-generated filename, PSR-3
logger wrapped in try/catch.
SeoMetaResource::find() handles dash-separated polymorphic
lookups. The admin frontend sends GET /api/seo_meta/discussions-42
to find-or-create the SeoMeta row for a subject; the v2 Resource's
Show endpoint normally requires a numeric id, so find() intercepts
the {type}-{id} form and short-circuits to
SeoMeta::findByObjectTypeOrCreate. Allowlist restricts type to
discussions/users/tags/pages.
What it does on every page
| Surface | What gets emitted |
|---|---|
| OpenGraph | og:site_name, og:type, og:title, og:description, og:url, og:image |
| Twitter Card | twitter:card, twitter:title, twitter:description, twitter:image, twitter:url |
| Robots directives | index/noindex, follow/nofollow, noarchive, noimageindex, nosnippet (per-route + per-row override via SeoMeta) |
| JSON-LD Schema.org | DiscussionForumPosting (with publisher Organization + author Person), BreadcrumbList, WebSite (with SearchAction for the sitelinks search box). QAPage instead of DiscussionForumPosting when fof/best-answer flags the thread answered. |
| Article metadata | article:published_time, article:updated_time |
| Canonical | <link rel="canonical"> on every route |
| Verification | google-site-verification, msvalidate.01, yandex-verification, p:domain_verify (when admin has configured the token) |
Quick start
composer require ernestdefoe/seo
php flarum migrate
php flarum cache:clear
Enable from Admin → Extensions → SEO. Open the SEO settings tab to
configure:
- Default fallback meta — site description, keywords, default
social-media image.
- Per-row overrides — open any discussion / tag / page and click
the SEO drawer to override the auto-generated title / description /
image / robots directives for that specific subject.
- Search Console Verification — paste the verification tokens from
Google / Bing / Yandex / Pinterest; meta tags appear on every page
on save.
Composer suggests
flarum/tags — when present, the Tags page renderer emits proper
category metadata + breadcrumb schema.fof/pages — when present, the Pages page renderer treats pages
as WebPage schema with publisher attribution.fof/best-answer — when present, discussions flagged as answered
switch from DiscussionForumPosting to QAPage schema, which
search engines render as a Q&A rich snippet.fof/sitemap — when present, owns /sitemap.xml with sitemap-index
pagination for forums larger than 50k URLs. We auto-defer to it.ernestdefoe/og-image — when present, auto-generates per-discussion
social images.
Compatibility & status
- Flarum: 2.0+ (requires
flarum/core: ^2.0).
- PHP: 8.3+.
- MySQL / MariaDB: any version that supports
utf8mb4_unicode_ci
(every version Flarum supports).
- License: MIT.
License & credits
MIT. Upstream credit:
v17development/flarum-seo
— this extension is a maintained Flarum 2 fork. Core architecture
(SeoMeta table, Page drivers, Content injector, Schema.org payload
shape) preserved from upstream.
