perf: add caching layer for frequently accessed operations

Add instance and result caching for hot paths in the rendering pipeline:

- ProjectNode: cache root document entry with O(1) lookup, add fast-path
  to getDocumentEntry(), lazy cache invalidation in setDocumentEntries()
- DocumentNode: add hasDocumentEntry() helper for safe checks
- RenderContext: use hash map for O(1) document lookup by file path,
  optimize withDocument() to clone directly instead of rebuilding
- DocumentNameResolver: cache URI analysis and resolved paths
- ExternalReferenceResolver: pre-compile schema regex pattern
- SluggerAnchorNormalizer: cache slugger instance and normalization results
- AbstractUrlGenerator: cache isRelativePath() checks
- RelativeUrlGenerator: cache computed relative paths
- PreNodeRendererFactory: cache renderer lookups by node class
- TwigEnvironmentBuilder: enable filesystem template caching
- TwigTemplateRenderer: cache global context to avoid redundant addGlobal()

See https://cybottm.github.io/render-guides/ for benchmark data.

Author: CybotTM

packages/guides/src/NodeRenderers/PreRenderers/PreNodeRendererFactory.php

@@ -21,9 +21,16 @@
 
 /**
  * Decorator to add pre-rendering logic to node renderers.
+ *
+ * Note: Caching assumes PreNodeRenderer::supports() only checks the node's
+ * class type, not instance-specific properties. If a PreNodeRenderer needs
+ * to check node properties, caching by class would return incorrect results.
  */
 final class PreNodeRendererFactory implements NodeRendererFactory
 {
+    /** @var array<class-string<Node>, NodeRenderer<Node>> */
+    private array $cache = [];
+
     public function __construct(
         private readonly NodeRendererFactory $innerFactory,
         /** @var iterable<PreNodeRenderer> */
@@ -33,6 +40,12 @@ public function __construct(
 
     public function get(Node $node): NodeRenderer
     {
+        // Cache by node class to avoid repeated preRenderer iteration
+        $nodeFqcn = $node::class;
+        if (isset($this->cache[$nodeFqcn])) {
+            return $this->cache[$nodeFqcn];
+        }
+
         $preRenderers = [];
         foreach ($this->preRenderers as $preRenderer) {
             if (!$preRenderer->supports($node)) {
@@ -43,9 +56,9 @@ public function get(Node $node): NodeRenderer
         }
 
         if (count($preRenderers) === 0) {
-            return $this->innerFactory->get($node);
+            return $this->cache[$nodeFqcn] = $this->innerFactory->get($node);
         }
 
-        return new PreRenderer($this->innerFactory->get($node), $preRenderers);
+        return $this->cache[$nodeFqcn] = new PreRenderer($this->innerFactory->get($node), $preRenderers);
     }
 }

packages/guides/src/Nodes/DocumentNode.php

@@ -279,6 +279,11 @@ public function getFootnoteTargetAnonymous(): FootnoteTarget|null
         return null;
     }
 
+    public function hasDocumentEntry(): bool
+    {
+        return $this->documentEntry !== null;
+    }
+
     public function getDocumentEntry(): DocumentEntryNode
     {
         if ($this->documentEntry === null) {

packages/guides/src/ReferenceResolvers/DocumentNameResolver.php

@@ -23,6 +23,18 @@
 
 final class DocumentNameResolver implements DocumentNameResolverInterface
 {
+    /** @var array<string, string> */
+    private array $absoluteUrlCache = [];
+
+    /** @var array<string, string> */
+    private array $canonicalUrlCache = [];
+
+    /** @var array<string, bool> */
+    private array $isAbsoluteCache = [];
+
+    /** @var array<string, bool> */
+    private array $isAbsolutePathCache = [];
+
     /**
      * Returns the absolute path, including prefixing '/'.
      *
@@ -31,20 +43,31 @@ final class DocumentNameResolver implements DocumentNameResolverInterface
      */
     public function absoluteUrl(string $basePath, string $url): string
     {
-        $uri = BaseUri::from($url);
-        if ($uri->isAbsolute()) {
-            return $url;
+        $cacheKey = $basePath . '|' . $url;
+        if (isset($this->absoluteUrlCache[$cacheKey])) {
+            return $this->absoluteUrlCache[$cacheKey];
+        }
+
+        // Cache URI analysis results separately by URL
+        if (!isset($this->isAbsoluteCache[$url])) {
+            $uri = BaseUri::from($url);
+            $this->isAbsoluteCache[$url] = $uri->isAbsolute();
+            $this->isAbsolutePathCache[$url] = $uri->isAbsolutePath();
+        }
+
+        if ($this->isAbsoluteCache[$url]) {
+            return $this->absoluteUrlCache[$cacheKey] = $url;
         }
 
-        if ($uri->isAbsolutePath()) {
-            return $url;
+        if ($this->isAbsolutePathCache[$url]) {
+            return $this->absoluteUrlCache[$cacheKey] = $url;
         }
 
         if ($basePath === '/') {
-            return $basePath . $url;
+            return $this->absoluteUrlCache[$cacheKey] = $basePath . $url;
         }
 
-        return '/' . trim($basePath, '/') . '/' . $url;
+        return $this->absoluteUrlCache[$cacheKey] = '/' . trim($basePath, '/') . '/' . $url;
     }
 
     /**
@@ -57,8 +80,13 @@ public function absoluteUrl(string $basePath, string $url): string
      */
     public function canonicalUrl(string $basePath, string $url): string
     {
+        $cacheKey = $basePath . '|' . $url;
+        if (isset($this->canonicalUrlCache[$cacheKey])) {
+            return $this->canonicalUrlCache[$cacheKey];
+        }
+
         if ($url[0] === '/') {
-            return ltrim($url, '/');
+            return $this->canonicalUrlCache[$cacheKey] = ltrim($url, '/');
         }
 
         $dirNameParts = explode('/', $basePath);
@@ -78,6 +106,6 @@ public function canonicalUrl(string $basePath, string $url): string
             $urlPass1[] = $part;
         }
 
-        return ltrim(implode('/', $dirNameParts) . '/' . implode('/', $urlPass1), '/');
+        return $this->canonicalUrlCache[$cacheKey] = ltrim(implode('/', $dirNameParts) . '/' . implode('/', $urlPass1), '/');
     }
 }

packages/guides/src/ReferenceResolvers/ExternalReferenceResolver.php

@@ -37,6 +37,8 @@ final class ExternalReferenceResolver implements ReferenceResolver
     public final const PRIORITY = -100;
     final public const SUPPORTED_SCHEMAS = '(?:aaa|aaas|about|acap|acct|acd|acr|adiumxtra|adt|afp|afs|aim|amss|android|appdata|apt|ar|ark|at|attachment|aw|barion|bb|beshare|bitcoin|bitcoincash|blob|bolo|browserext|cabal|calculator|callto|cap|cast|casts|chrome|chrome-extension|cid|coap|coap+tcp|coap+ws|coaps|coaps+tcp|coaps+ws|com-eventbrite-attendee|content|content-type|crid|cstr|cvs|dab|dat|data|dav|dhttp|diaspora|dict|did|dis|dlna-playcontainer|dlna-playsingle|dns|dntp|doi|dpp|drm|drop|dtmi|dtn|dvb|dvx|dweb|ed2k|eid|elsi|embedded|ens|ethereum|example|facetime|fax|feed|feedready|fido|file|filesystem|finger|first-run-pen-experience|fish|fm|ftp|fuchsia-pkg|geo|gg|git|gitoid|gizmoproject|go|gopher|graph|grd|gtalk|h323|ham|hcap|hcp|http|https|hxxp|hxxps|hydrazone|hyper|iax|icap|icon|im|imap|info|iotdisco|ipfs|ipn|ipns|ipp|ipps|irc|irc6|ircs|iris|iris\.beep|iris\.lwz|iris\.xpc|iris\.xpcs|isostore|itms|jabber|jar|jms|keyparc|lastfm|lbry|ldap|ldaps|leaptofrogans|lorawan|lpa|lvlt|magnet|mailserver|mailto|maps|market|matrix|message|microsoft\.windows\.camera|microsoft\.windows\.camera\.multipicker|microsoft\.windows\.camera\.picker|mid|mms|modem|mongodb|moz|ms-access|ms-appinstaller|ms-browser-extension|ms-calculator|ms-drive-to|ms-enrollment|ms-excel|ms-eyecontrolspeech|ms-gamebarservices|ms-gamingoverlay|ms-getoffice|ms-help|ms-infopath|ms-inputapp|ms-launchremotedesktop|ms-lockscreencomponent-config|ms-media-stream-id|ms-meetnow|ms-mixedrealitycapture|ms-mobileplans|ms-newsandinterests|ms-officeapp|ms-people|ms-project|ms-powerpoint|ms-publisher|ms-remotedesktop|ms-remotedesktop-launch|ms-restoretabcompanion|ms-screenclip|ms-screensketch|ms-search|ms-search-repair|ms-secondary-screen-controller|ms-secondary-screen-setup|ms-settings|ms-settings-airplanemode|ms-settings-bluetooth|ms-settings-camera|ms-settings-cellular|ms-settings-cloudstorage|ms-settings-connectabledevices|ms-settings-displays-topology|ms-settings-emailandaccounts|ms-settings-language|ms-settings-location|ms-settings-lock|ms-settings-nfctransactions|ms-settings-notifications|ms-settings-power|ms-settings-privacy|ms-settings-proximity|ms-settings-screenrotation|ms-settings-wifi|ms-settings-workplace|ms-spd|ms-stickers|ms-sttoverlay|ms-transit-to|ms-useractivityset|ms-virtualtouchpad|ms-visio|ms-walk-to|ms-whiteboard|ms-whiteboard-cmd|ms-word|msnim|msrp|msrps|mss|mt|mtqp|mumble|mupdate|mvn|news|nfs|ni|nih|nntp|notes|num|ocf|oid|onenote|onenote-cmd|opaquelocktoken|openpgp4fpr|otpauth|p1|pack|palm|paparazzi|payment|payto|pkcs11|platform|pop|pres|prospero|proxy|pwid|psyc|pttp|qb|query|quic-transport|redis|rediss|reload|res|resource|rmi|rsync|rtmfp|rtmp|rtsp|rtsps|rtspu|sarif|secondlife|secret-token|service|session|sftp|sgn|shc|shttp (OBSOLETE)|sieve|simpleledger|simplex|sip|sips|skype|smb|smp|sms|smtp|snews|snmp|soap\.beep|soap\.beeps|soldat|spiffe|spotify|ssb|ssh|starknet|steam|stun|stuns|submit|svn|swh|swid|swidpath|tag|taler|teamspeak|tel|teliaeid|telnet|tftp|things|thismessage|tip|tn3270|tool|turn|turns|tv|udp|unreal|upt|urn|ut2004|uuid-in-package|v-event|vemmi|ventrilo|ves|videotex|vnc|view-source|vscode|vscode-insiders|vsls|w3|wais|web3|wcr|webcal|web+ap|wifi|wpid|ws|wss|wtai|wyciwyg|xcon|xcon-userid|xfire|xmlrpc\.beep|xmlrpc\.beeps|xmpp|xri|ymsgr|z39\.50|z39\.50r|z39\.50s)';
 
+    private const SCHEMA_PATTERN_REGEX = '/^' . self::SUPPORTED_SCHEMAS . '$/';
+
     public function resolve(LinkInlineNode $node, RenderContext $renderContext, Messages $messages): bool
     {
         if (str_starts_with($node->getTargetReference(), '#')) {
@@ -52,7 +54,7 @@ public function resolve(LinkInlineNode $node, RenderContext $renderContext, Mess
         }
 
         $url = parse_url($node->getTargetReference(), PHP_URL_SCHEME);
-        if ($url !== null && $url !== false && preg_match('/^' . self::SUPPORTED_SCHEMAS . '$/', $url)) {
+        if ($url !== null && $url !== false && preg_match(self::SCHEMA_PATTERN_REGEX, $url)) {
             $node->setUrl($node->getTargetReference());
 
             return true;

packages/guides/src/ReferenceResolvers/SluggerAnchorNormalizer.php

@@ -19,11 +19,28 @@
 
 final class SluggerAnchorNormalizer implements AnchorNormalizer
 {
+    private AsciiSlugger|null $slugger = null;
+
+    /** @var array<string, string> */
+    private array $cache = [];
+
     public function reduceAnchor(string $rawAnchor): string
     {
-        $slugger = new AsciiSlugger();
-        $slug = $slugger->slug($rawAnchor);
+        // Check cache first - same anchors are resolved many times
+        if (isset($this->cache[$rawAnchor])) {
+            return $this->cache[$rawAnchor];
+        }
+
+        if ($this->slugger === null) {
+            $this->slugger = new AsciiSlugger();
+        }
+
+        $slug = $this->slugger->slug($rawAnchor);
+        $result = strtolower($slug->toString());
+
+        // Cache the result for future calls
+        $this->cache[$rawAnchor] = $result;
 
-        return strtolower($slug->toString());
+        return $result;
     }
 }

packages/guides/src/RenderContext.php

@@ -30,6 +30,9 @@ class RenderContext
     /** @var DocumentNode[] */
     private array $allDocuments;
 
+    /** @var array<string, DocumentNode> */
+    private array $documentsByFile = [];
+
     private string $outputFilePath = '';
 
     private Renderer\DocumentListIterator $iterator;
@@ -44,7 +47,10 @@ private function __construct(
     ) {
     }
 
-    /** @param DocumentNode[] $allDocumentNodes */
+    /**
+     * @param DocumentNode[] $allDocumentNodes
+     * @param array<string, DocumentNode>|null $documentsByFile Pre-built hash map for reuse
+     */
     public static function forDocument(
         DocumentNode $documentNode,
         array $allDocumentNodes,
@@ -53,6 +59,7 @@ public static function forDocument(
         string $destinationPath,
         string $ouputFormat,
         ProjectNode $projectNode,
+        array|null $documentsByFile = null,
     ): self {
         $self = new self(
             $destinationPath,
@@ -65,22 +72,40 @@ public static function forDocument(
 
         $self->document = $documentNode;
         $self->allDocuments = $allDocumentNodes;
-        $self->outputFilePath =  $documentNode->getFilePath() . '.' . $ouputFormat;
+
+        // Use pre-built hash map if provided, otherwise build it
+        if ($documentsByFile !== null) {
+            $self->documentsByFile = $documentsByFile;
+        } else {
+            foreach ($allDocumentNodes as $doc) {
+                if (!$doc->hasDocumentEntry()) {
+                    continue;
+                }
+
+                $self->documentsByFile[$doc->getDocumentEntry()->getFile()] = $doc;
+            }
+        }
+
+        $self->outputFilePath = $documentNode->getFilePath() . '.' . $ouputFormat;
 
         return $self;
     }
 
     public function withDocument(DocumentNode $documentNode): self
     {
-        return self::forDocument(
+        // Pass existing hash map to avoid redundant construction
+        $context = self::forDocument(
             $documentNode,
             $this->allDocuments,
             $this->origin,
             $this->destination,
             $this->destinationPath,
             $this->outputFormat,
             $this->projectNode,
-        )->withIterator($this->getIterator());
+            $this->documentsByFile,
+        );
+
+        return $context->withIterator($this->getIterator());
     }
 
     public function getDocument(): DocumentNode
@@ -121,6 +146,14 @@ public static function forProject(
         );
 
         $self->allDocuments = $allDocumentNodes;
+        // Build hash map for O(1) document lookup
+        foreach ($allDocumentNodes as $doc) {
+            if (!$doc->hasDocumentEntry()) {
+                continue;
+            }
+
+            $self->documentsByFile[$doc->getDocumentEntry()->getFile()] = $doc;
+        }
 
         return $self;
     }
@@ -222,10 +255,10 @@ public function getProjectNode(): ProjectNode
 
     public function getDocumentNodeForEntry(DocumentEntryNode $entryNode): DocumentNode
     {
-        foreach ($this->allDocuments as $child) {
-            if ($child->getDocumentEntry() === $entryNode) {
-                return $child;
-            }
+        // O(1) lookup using hash map instead of O(n) iteration
+        $file = $entryNode->getFile();
+        if (isset($this->documentsByFile[$file])) {
+            return $this->documentsByFile[$file];
         }
 
         throw new Exception('No document was found for document entry ' . $entryNode->getFile());

packages/guides/src/Renderer/UrlGenerator/AbstractUrlGenerator.php

@@ -26,6 +26,9 @@
 
 abstract class AbstractUrlGenerator implements UrlGeneratorInterface
 {
+    /** @var array<string, bool> */
+    private array $relativeUrlCache = [];
+
     public function __construct(private readonly DocumentNameResolverInterface $documentNameResolver)
     {
     }
@@ -93,7 +96,11 @@ public function generateInternalUrl(
 
     private function isRelativeUrl(string $url): bool
     {
-        return BaseUri::from($url)->isRelativePath();
+        if (isset($this->relativeUrlCache[$url])) {
+            return $this->relativeUrlCache[$url];
+        }
+
+        return $this->relativeUrlCache[$url] = BaseUri::from($url)->isRelativePath();
     }
 
     public function getCurrentFileUrl(RenderContext $renderContext): string

packages/guides/src/Renderer/UrlGenerator/RelativeUrlGenerator.php

@@ -26,18 +26,28 @@
 
 final class RelativeUrlGenerator extends AbstractUrlGenerator
 {
+    /** @var array<string, string> */
+    private array $pathCache = [];
+
     public function generateInternalPathFromRelativeUrl(
         RenderContext $renderContext,
         string $canonicalUrl,
     ): string {
-        $currentPathUri = Uri::new($renderContext->getOutputFilePath());
+        $outputFilePath = $renderContext->getOutputFilePath();
+        $cacheKey = $outputFilePath . '|' . $canonicalUrl;
+
+        if (isset($this->pathCache[$cacheKey])) {
+            return $this->pathCache[$cacheKey];
+        }
+
+        $currentPathUri = Uri::new($outputFilePath);
         $canonicalUrlUri = Uri::new($canonicalUrl);
 
         $canonicalAnchor = $canonicalUrlUri->getFragment();
 
         // If the paths are the same, include the anchor
         if ($currentPathUri->getPath() === $canonicalUrlUri->getPath()) {
-            return '#' . $canonicalAnchor;
+            return $this->pathCache[$cacheKey] = '#' . $canonicalAnchor;
         }
 
         // Split paths into arrays
@@ -66,6 +76,6 @@ public function generateInternalPathFromRelativeUrl(
             $relativePath .= '#' . $canonicalAnchor;
         }
 
-        return $relativePath;
+        return $this->pathCache[$cacheKey] = $relativePath;
     }
 }

packages/guides/src/Twig/EnvironmentBuilder.php

@@ -15,10 +15,13 @@
 
 use phpDocumentor\Guides\RenderContext;
 use phpDocumentor\Guides\Twig\Theme\ThemeManager;
+use Twig\Cache\FilesystemCache;
 use Twig\Environment;
 use Twig\Extension\DebugExtension;
 use Twig\Extension\ExtensionInterface;
 
+use function sys_get_temp_dir;
+
 final class EnvironmentBuilder
 {
     private Environment $environment;
@@ -28,7 +31,10 @@ public function __construct(ThemeManager $themeManager, iterable $extensions = [
     {
         $this->environment = new Environment(
             $themeManager->getFilesystemLoader(),
-            ['debug' => true],
+            [
+                'debug' => true,
+                'cache' => new FilesystemCache(sys_get_temp_dir() . '/guides-twig-cache'),
+            ],
         );
         $this->environment->addExtension(new DebugExtension());