Skip to content

Document the themed-view opt-out, the parser app variable, translator autowiring and PHPStan include merging - #7

Merged
anoziere merged 1 commit into
mainfrom
docs/document-thelia3-runtime-pitfalls
Aug 18, 2026
Merged

Document the themed-view opt-out, the parser app variable, translator autowiring and PHPStan include merging#7
anoziere merged 1 commit into
mainfrom
docs/document-thelia3-runtime-pitfalls

Conversation

@anoziere

Copy link
Copy Markdown
Member

Four Thelia 3 behaviours that cost time in real work and that no skill described yet, plus two follow-ups left open by the previous documentation pass. Each claim was checked against the current core, the Flexy theme and the default-twig theme before being written.

Routes that are not views need ignore_thelia_view

ViewListener subscribes to kernel.view, so any controller that does not return a Response gets a themed view rendered for it. A module route with no _view reaches ViewRenderer with an empty view name, which logs No view found and throws a NotFoundHttpException — and ErrorListener then replaces that, in production, with the theme's error page. The endpoint answers a themed 404 and the only trace is one line in the Thelia log.

The skills already mentioned the flag for the /_components route. What was missing is the general rule and the fact that it is one flag with three effects: the view listener, the admin firewall check in ControllerListener, and the themed error page in ErrorListener all key on the same request attribute. Opting out therefore also means the route has to guard itself, and has to return a real Response.

The parser's app is not Symfony's AppVariable

TwigParser::render() puts its own app in the render context: a plain object with environment, request, session and debug, and no methods. A context variable shadows a Twig global, so every template the parser renders sees that stub. With strict_variables off outside the test environment, app.flashes(...), app.user, app.token and app.locale all resolve to null in silence — which is why the Flexy theme reads flashes as app.session.flashBag.get(...).

The back-office is not in the same position: its controllers render through the injected Twig Environment, so its templates get the real AppVariable and do use app.flashes. Which app you get depends on who renders the template.

TranslatorInterface autowires to Thelia's translator

The core aliases Symfony\Contracts\Translation\TranslatorInterface to Thelia\Core\Translation\Translator, so a constructor type-hinting the interface never gets the Symfony one. That translator carries the module and validator catalogs, not translations/messages.<locale>.php, so a key defined for the templates comes back unchanged from PHP. The escape hatch is #[Autowire(service: 'translator')], which is what the Flexy theme uses in its controllers, services and forms.

The back-office skill already described the two translators; this adds why you get one rather than the other, and how to ask for the other.

A PHPStan includes: merges paths

Array parameters are merged, not overwritten, so a config that includes the root one and adds its own paths analyses both. Scalars override, so a config that does not restate level silently runs at the included level. paths!: replaces; dump-parameters shows the merged result.

Also in this PR

  • The production asset step, which no install script runs: tailwind:build --minify and asset-map:compile. AssetMapper's dev server follows the debug flag, so a front office deployed without the compile has no CSS and no JavaScript.
  • Removed the messenger:consume async post-start hook from the DDEV skill. Thelia 3 does not ship symfony/messenger, and the Thelia 3 skill already says so.

@anoziere
anoziere merged commit a41656c into main Aug 18, 2026
2 checks passed
@anoziere
anoziere deleted the docs/document-thelia3-runtime-pitfalls branch August 18, 2026 12:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant