[TASK] Add caching layer for rendering operations

[CybotTM]

Summary

Adds caching layers for frequently accessed rendering operations to improve performance.

Changes

• SluggerAnchorNormalizer: Cache slugger instance and normalization results
• TwigTemplateRenderer: Cache Twig globals across render calls
• PreNodeRendererFactory: Cache renderer lookups by class name
• TwigEnvironment: Cache template by path
• RenderContext: O(1) document lookup via hash map
• DocumentNameResolver: Cache URL resolution results
• UrlGenerator: Cache URL generation results
• ExternalReferenceResolver: O(1) hash set lookup for URI schemes (~6x faster than regex)

Performance Impact

See Performance Analysis Report for detailed benchmarks.

---

Related PRs

PR	Description	Status
#1287	This PR - Rendering caching layer
#1288	RST parsing optimizations	Open, reworked after review
#1289	CLI container caching	Closed — the cache was never written
#1291	Symfony 8 compatibility	✅ Merged
#1293	ProjectNode O(1) document lookup	Independent

All PRs can be merged independently in any order.

Update: reworked after review

The Twig compile cache is gone, and EnvironmentBuilder is byte-identical to main again. @jaapio's point stands on its own — a compile cache only pays off where the filesystem survives between runs, which is not where this tool mostly runs, and @garvinhicking confirmed that for the TYPO3 pipeline. Independently of that it was unconditional and pointed at a fixed path in the shared temp directory: the second user to build on a shared runner hits "Unable to write in the cache directory", the load path include_onces PHP from a world writable place, and a template whose mtime moves backwards is served stale indefinitely.

PreNodeRendererFactory follows @jaapio's suggestion. There is a new PreNodeRendererCachableSupports interface with cacheSupport(): bool, and the factory decides once per node class only when every pre-renderer implements it and returns true. supports() receives a node instance and may inspect its state, so caching by class froze whatever the first node of a class happened to yield — a third party pre-renderer answering for external links only would have been switched off for the whole build by the first internal one. Both pre-renderers here look at the class alone and say so. Two unit tests cover both directions.

The relative path cache is held for one document instead of being keyed by output file. The generator lives for the whole render and every document renders the same site wide menu, so the old key let the table grow as documents times link targets. The repetition it exploits is within a document, so the speedup survives while the size no longer depends on the number of documents.

The globals memo in TwigTemplateRenderer is keyed on the environment as well as the context. EnvironmentBuilder::setEnvironmentFactory() is public API and its replacement carries no globals, so the memo would have skipped re-applying them and every template would have rendered against env = null.

The four remaining review threads are the ones answered with measurements; those are left as they are.

Assisted by claude-code:claude-opus-5 — Session

[jaapio]

Thanks for these improvements. I see a lot of very nice spots to focus on. And some really good suggestions.
I can see how many on these changes would safe cpu cycles. But I'm a little concerned about the memory impact of some of the changes.

Please keep in mind that this tool is running mostly in CI enviroments in single runs. Not many people are using it as a quick feedback tool. And if they do, they use the build in dev-server that gives them response in less than a second.

Maybe we can split the parts that we are more sure about from the debatable topics to make the improvements land fast, and not block the whole pr. Ofcourse I can be wrong at specify topics. But the attached benchmark does not really show the improvements in this specify PR if I understand that correctly?
Maybe we can use some small benchmarks to show the improvements and impact of the changes in the smaller algorithms. I'm open to help you with that. Before I used phpBench and xdebug profiles to test simple algorithms in isolation. And pushed thousands of variants through logic to verify the improvements.

[jaapio]

We cannot make sure nobody is relying on this behavior. I concider this to be a breaking change. I see how this could improve the speed, but the actual impact of this change might be limited.

What we could do is introduce a new interface that can be implemented by the PreNodeRenderer that already exist.
PreNodeRendererCachableSupports would have a method cacheSupport() : bool

When preRenderers is not empty and all preRenderers are cachable, we can create add it to cache.

I think that will make sure we are backward compatible but still can cache the node renderers.

[CybotTM]

Implemented as you suggested, in 3be2457. There is now a PreNodeRendererCachableSupports interface with cacheSupport(): bool; PreNodeRendererFactory decides once per node class only when every pre-renderer implements it and returns true, and falls back to asking per node otherwise. Both pre-renderers in this repository look at the node class alone and say so, while a third party one that inspects instance state keeps working — previously the first node of a class would have frozen the answer for the whole build. Two unit tests cover both directions.

[jaapio]

I'm wondering how much this would improve. There is not much heavy logic in this method. And I think the actual increase of memory usage does not add up to the small improvement this change has.

A more specify benchmark on this method could help me to understand why this improves the speed.

[CybotTM]

BaseUri::from($url) is quite heavy!

absoluteUrl() performance for Documentation-rendertest:

Scenario	Calls	Time/call	Total time	Memory	Speedup
Old (singleton)	355	3.95 µs	1.40 ms	0 KB	-
New (singleton)	355	0.08 µs	0.03 ms	+66 KB	53x
Old (new instance)	355	3.97 µs	1.41 ms	0 KB	-
New (new instance)	355	2.00 µs	0.71 ms	+66 KB	2x

"new instance" means if DocumentNameResolver would use a new instance for every document but it is a Symfony service (singleton).

[jaapio]

Maybe we can combine the logic of building the cache and finding the correct entry in here, This would prevent extra load for the people not using the getDocumentNodeForEntry. And also centralizes the creating which is now in two methods.

We could still pass the cache to the new instance like you do right now. Which would speed up things. 👍

[jaapio]

I do not see the value of this extra cache. I think the extra memory consumption is not worth the less cpu cycles.

[CybotTM]

For Documentation-rendertest

Calls per render	7,566
Unique	969
Repetition rate	87%

Scenario	Time/call	Total time	Memory	Speedup
Old (no cache)	3.82 µs	28.9 ms	0 KB	-
New (with cache)	0.01 µs	0.1 ms	+40 KB	280x

[CybotTM]

The measured numbers still hold, but your concern about the memory does too, and it was the sharper problem here: the key contained the output file, so on a service that lives for the whole render and a manual where every document renders the same site wide menu, the table grew as documents times link targets. In 3be2457 the cache is held for one document and dropped when the next one starts. The repetition it exploits is within a document, so the speedup survives, and the size no longer depends on the number of documents.

[jaapio]

Adding twig cache only adds value when the filesystem persists between runs. Which is not the case for people using this tool in CI or in docker. The extra file writes do even slow down the execution in the benchmarks I did in the past. This is why there is no cache enabled in this project.

[CybotTM]

Adding twig cache only adds value when the filesystem persists between runs.

You are right, twig has an in-memory cache. I missed this.

Which is not the case for people using this tool in CI or in docker.

You do not know how people are using this, nor how they are using this in their CI or how they use the container. Caching is also easy possible in CI and/or with container.

using this tool in CI or in docker

Would also not require supporting PHP 8.1 - 8.5 ... ;-)

The use-case was repeated rendering while working on the docs. Or repeated rendering of different docs. Dunno how TYPO3 docs deployment works currently - with an ever running job benefitting from in-memory caching, or new processes for every new docs package without caching.

[garvinhicking]

(TYPO3 CI docs deployment runs are performed with a usual clean runner; IIRC some composer packages are cached. But the render is performed with a fresh env using the docker container that has no state.)

[CybotTM]

You are right, and it is removed in 3be2457. Beyond the point you make about the filesystem not surviving between runs, the cache was unconditional and pointed at a fixed path in the shared temp directory: on a shared runner the second user to build hits "Unable to write in the cache directory", the load path include_onces PHP from a world writable place, and a template whose mtime moves backwards — rsync -t, a tarball, a fixed SOURCE_DATE_EPOCH — is served stale indefinitely. The file is back to what main has.

[jaapio]

I would be very surprised if this would improve the performance of the application. But as this method is called hundreds of times in a normal render, if could.

[CybotTM]

for Documentation-rendertest

Metric	Old	New	Notes
Call counts
addGlobal() calls	57,070	72	99.9% reduction
getLoggerInformation() calls	28,535	36	Only on context change
Simulated renderTemplate() only			~30k calls, trivial template
Time	36.25 ms	30.58 ms	15.6% faster
Savings	-	5.67 ms
Full Documentation-rendertest			Parsing, compiling, I/O, etc.
Estimated total time	~2-4 sec	~2-4 sec	5.67 ms = ~0.2% of total

[jaapio]

Would a simple array_flip not be faster?

[CybotTM]

This is called only once during a whole documentation rendering process. And both methods are equal ~1.3µs.