Skip to content

Conversation

@CybotTM
Copy link
Contributor

@CybotTM CybotTM commented Jan 23, 2026

Summary

Introduces CachingParseFileHandler that decorates ParseFileHandler to cache parsed document AST, avoiding re-parsing unchanged files.

Features

  • Content-hash based caching: Detects unchanged files via xxh128 hash of content + config
  • File-based caching: Stores serialized DocumentNode in system temp directory with configurable TTL (default 24 hours)
  • In-memory caching: Deduplicates parse requests within the same render process
  • Smart cache key: Includes file contents, path, initial header level, and root flag

Performance Impact

~40% parse time reduction for unchanged files during incremental builds.

Technical Details

  • Decorator pattern: CachingParseFileHandler wraps existing ParseFileHandler
  • PHP 8.1 compatible
  • Cache location: {sys_temp_dir}/typo3-guides-ast-cache/
  • Serialized PHP objects with class allowlisting
  • TTL validation prevents stale cache usage

Part of Performance Initiative

This is Phase 1.2 of the performance optimization initiative tracked in #1143.

Related PRs:

  • #1152 - Inventory caching (Phase 1.1)

Upstream dependencies (phpdocumentor/guides):

  • #1287 - DocumentEntryNode file path method
  • #1288 - DocumentEntryNode isRoot flag
  • #1289 - ProjectNode find method
  • #1293 - O(1) document lookup optimization

Test plan

  • Run render on documentation project
  • Verify AST cache files created in temp directory
  • Modify source file and verify re-parse occurs
  • Leave file unchanged and verify cache hit
  • Test cache expiration after TTL

Introduces CachingParseFileHandler that decorates ParseFileHandler with:
- Content-hash based caching to detect unchanged files
- File-based caching with configurable TTL (default 24 hours)
- In-memory caching for current request deduplication
- ~40% parse time reduction for unchanged files

Cache key includes file contents, path, header level, and root flag.
Serialized DocumentNode stored in system temp directory.
PHP 8.1 compatible.
- Use PHP 8.1 octal notation (0o755)
- Compact empty constructor braces
@CybotTM
Copy link
Contributor Author

CybotTM commented Jan 23, 2026

Closing due to integration issues with Symfony's service decoration pattern. The AST caching decorator conflicts with how ParseFileHandler is used in the message bus. Will revisit with a different approach (possibly event-based caching).

@CybotTM CybotTM closed this Jan 23, 2026
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