[albertlast]

Description

This replaces SMF's own template mechanism, template_*() functions that echo, with Plates (league/plates 3.6), and converts every template in the default theme. The forum renders what it rendered before. The one exception is the theme copy page, which had to learn the new layout.

This is stacked on #9727 (part 1, the converter), which is stacked on #9712 (the snapshot tests). Until both merge, this PR's diff includes their commits. The ones that belong here start at "Renders a sub-template with Plates when its theme has one".

How to review it

The diff is large, but almost all of it is generated: 54 *.template.php files deleted and 342 Plates files added under Themes/default/templates/. Those are the converter's output (part 1), with one exception, Stats, which was converted by hand as the first test of the engine. The generated files are reproducible from a clean checkout:

.dev/convert-templates.sh --from ea5ae213e --all --skip Stats

The part written by hand is about 700 lines in Sources/, plus tests:

File	What
Sources/TemplateEngine.php	wraps a Plates Engine with SMF's theme inheritance
Sources/Theme.php	loadTemplate() / loadSubTemplate() render either kind
Sources/TemplateFunctions.php	the template_*() helpers that mods call directly, kept working
Sources/Actions/Admin/Themes.php, ACP.php, ThemeChooser.php	the theme admin pages learn the new layout
ServerSideIncludes.php, WatchedUsers.php, Permissions.php	three direct calls to template functions
tests/Unit/TemplateEngineTest.php, tests/Integration/Http/ThemeCopyTest.php	tests

Design

• Layout. A template is a directory: Themes/<theme>/templates/<Template>/<sub_template>.php. Theme::loadTemplate('Display') finds the directory, and Theme::loadSubTemplate('main') renders Display/main.php.
• Inheritance, per file. Plates' theme hierarchy follows template_dirs: current theme, then the base theme, then default. A theme overrides a single sub-template by shipping that one file, where it used to copy the whole *.template.php.
• Both kinds at once. Themes that aren't converted keep working unchanged. The first theme directory that has a template decides its kind. Where both kinds define the same sub-template, the template loaded last wins.
  • A converted template calls another sub-template through $this->subTemplate('name', [...]), which works whichever kind has it. Two siblings support that call: $this->fetchSubTemplate() returns the output instead of printing it, and $this->hasSubTemplate() checks whether a sub-template exists.
• Mods. The helpers mods call from their own templates are still defined as functions when their template loads, and each renders its Plates file. They are template_button_strip(), template_quickbuttons(), template_menu(), theme_linktree(), template_show_list(), template_control_richedit(), template_control_richedit_buttons() and template_control_verification().
• Data. Templates still read Utils::$context, Config, Lang and friends, as before. Passing each template its data explicitly is the natural next step, and a separate one: it would change every file by hand and lose the byte-for-byte comparison that makes this PR checkable.
• Plates bug worked around. With Engine::fromTheme(), Engine::exists() and Engine::path() ignore the theme hierarchy, so the engine goes through Template::exists() / path() instead.

Backwards compatibility

• Custom themes with *.template.php files: unchanged.
• Mods that call the helpers above: unchanged, as are mods that define their own template_*() functions and load them through loadTemplate().
• Mods that patch Themes/default/*.template.php through the package manager break. The files they search no longer exist, and there's no faithful way to redirect a search-and-replace into the new files, which use different syntax. Such mods need updating for 3.0 anyway, but this makes it certain, and it probably deserves a note for mod authors.

Verified

• Page by page, on both engines, with part 1's capture and comparison. Before the final tidying commit, 460 of 464 pages were byte-identical to the old templates. The other four were the theme copy page, changed on purpose, and PostgreSQL tie ordering. After tidying, every page renders the same (--rendered). The only differences are ties in sort order: the stats top tens ([3.0] Ranks ties in the stats top tens in a defined order #9722) and the admin log ([3.0] Lists tied moderation log entries in a defined order #9726).
• What the snapshots don't cover: ssi_examples.php, XML responses, and a probe calling the helpers above the way a mod does. All identical.
• Suites: unit, integration, HTTP and snapshot all pass on MySQL and PostgreSQL (691 tests). TemplateEngineTest adds 20 unit tests for the engine: inheritance, mixed kinds, which one wins, argument passing, and the legacy helpers.

Overlap with other PRs

• The theme copy page gains the session check from [3.0] Checks the session before copying a template into a theme #9717, because the page had to be reworked for the new layout. Whichever of the two merges second drops the duplicate, and the two ThemeCopyTest files get merged.
• After [3.0] Lets moderators track another member's IP addresses #9718 merges, the admin/profile_track_ip snapshot from [3.0] Adds template snapshot tests that freeze what each page renders #9712 needs re-recording, because it currently records that page's fatal error.

Issues References (Fixes|Related|Closes)

Related: #9712, #9727 (part 1 of 2), #9717.

🤖 Generated with Claude Code

[jdarwood007]

I only clicked around and didn't even determine whether this is what we are doing.

I want to see how this handles compatibility with 2.1. It is understood that because we have changed CSS, we may have some presentation issues (we should try to limit those). But being able to call the theme functions and methods (including JS) should still work.

[jdarwood007]

We would need a compat function here.

[albertlast]

template_menu() still exists as a function. Sources/TemplateFunctions.php defines it whenever the index template is loaded from Plates, together with template_button_strip(), template_quickbuttons(), theme_linktree(), template_show_list() and the three GenericControls functions. Each of them renders its Plates file, so a mod that calls template_menu() directly keeps working.

This line only changes how SSI itself renders the menu. Theme::loadSubTemplate('menu') renders whichever kind the theme has, so a theme with its own index.template.php still gets its own template_menu(). ssi_examples.php, plus a script that calls ssi_menubar(), template_button_strip(), template_quickbuttons() and theme_linktree() the way a mod would, render byte-identically before and after this PR (.dev/plates/probe.php in #9727).

[albertlast]

Thanks for looking. I agree 2.1 compatibility needs an answer, but I think the answer has to account for where the templates are going next, not only for this PR.

What this PR keeps working

• Themes with *.template.php files load as before, and a theme can mix both kinds: override one template the old way and inherit the rest from Plates.
• The helpers that templates and mods call across files still exist as functions (see the inline reply).
• No JS, no CSS, and no Theme method besides loadTemplate()/loadSubTemplate() changes here. Whatever a theme calls in those works exactly as it does on release-3.0.

A gap I found while checking
2.1.7's default theme makes three cross-file template calls that have no compatibility function yet:

• template_topic_legend(), called from Recent, defined in MessageIndex
• template_options(), called from Profile, defined in Settings
• template_admin_quick_search(), called from GenericMenu, defined in Admin

So a 2.1 theme that overrides Recent.template.php would hit an undefined function.

Why I'd rather not chase full 2.1 theme compatibility
Every compatibility function freezes an old signature and keeps a second rendering path alive. That's affordable once. But the gap to 2.1 won't stay where it is:

• 3.0 has already changed the CSS.
• The next step we have in mind is moving the inline JS out of the templates. Today's templates, and 2.1's, set variables and wire up behaviour inline; after that step they won't, and a 2.1 template that relies on them breaks regardless of Plates.
• After that, passing templates their data explicitly instead of reading Utils::$context widens the gap again.

Runtime compatibility with 2.1 themes would mean rebuilding a compatibility layer at each of those steps, and each step makes the next one harder. Over time it costs more and delivers less.

What I'd propose instead

• For theme authors, a migration path rather than runtime compatibility. The converter in [3.0] Adds a repeatable converter from template functions to Plates templates (part 1 of 2) #9727 (.dev/plates/convert.php) converts any theme's *.template.php files to Plates, not only the default theme's. It translates the syntax mechanically; adapting to 3.0's markup, CSS and JS is still the author's job, as it would be anyway.
• For mods, a small, fixed set of helpers. These are the functions mods call from their own templates: the ones above, plus the three missing ones if we want them. All of it lives in Sources/TemplateFunctions.php, marked deprecated with a removal target. Taking it out later is then a deletion, not a refactor. The list can't grow, because it's bounded by 2.1.7.
• For JS, a decision in the PR that moves it out. The global function names (smc_Toggle, smf_* and so on) can stay as they are, which is cheap. The inline variables are what 2.1 code depends on, and that PR is where to decide what happens to them.

Since this decides more than this PR (it applies equally to the CSS work and the JS extraction), could we settle how much 2.1 theme compatibility 3.0 promises before I add more compatibility code here? If the answer is "mods yes, whole themes no", I'll add the three missing helpers and stop there.