[FEATURE] PHP 8.5 with parallel rendering and performance optimizations

.ddev/config.yaml

@@ -1,7 +1,7 @@
 name: render-guides
 type: php
 docroot: Documentation-GENERATED-temp
-php_version: "8.1"
+php_version: "8.5"
 webserver_type: nginx-fpm
 router_http_port: "80"
 router_https_port: "443"
@@ -24,7 +24,7 @@ nodejs_version: "18"
 
 # docroot: <relative_path> # Relative path to the directory containing index.php.
 
-# php_version: "8.1"  # PHP version to use, "5.6", "7.0", "7.1", "7.2", "7.3", "7.4", "8.0", "8.1", "8.2", "8.3"
+# php_version: "8.5"  # PHP version to use, "8.1", "8.2", "8.3", "8.4", "8.5"
 
 # You can explicitly specify the webimage but this
 # is not recommended, as the images are often closely tied to DDEV's' behavior,

.github/workflows/docker-test.yaml

@@ -10,7 +10,7 @@ on: # yamllint disable-line rule:truthy
 name: "Test Dockerfile"
 
 env:
-  DEFAULT_PHP_VERSION: "8.1"
+  DEFAULT_PHP_VERSION: "8.5"
   RUN_ENVIRONMENT: "local"
 
 jobs:

.github/workflows/main.yaml

@@ -7,7 +7,7 @@ on: # yamllint disable-line rule:truthy
       - "main"
 
 env:
-  DEFAULT_PHP_VERSION: "8.1"
+  DEFAULT_PHP_VERSION: "8.5"
   RUN_ENVIRONMENT: "local"
 
 jobs:
@@ -18,10 +18,7 @@ jobs:
       fail-fast: false
       matrix:
         php:
-          - '8.1'
-          - '8.2'
-          - '8.3'
-          - '8.4'
+          - '8.5'
     steps:
       - name: Checkout
         uses: actions/checkout@v4

.gitignore

@@ -7,3 +7,11 @@
 /Documentation-GENERATED-*
 /.phpdoc/
 /phpdoc.dist.xml
+*-temp/
+
+# Benchmark test documentation (downloaded on demand)
+/benchmark/test-docs/
+!/benchmark/test-docs/.gitkeep
+
+# Benchmark results (environment-specific, accumulate over time)
+benchmark/results/*.json

BENCHMARK_PLAN.md

@@ -0,0 +1,163 @@
+# Performance Benchmark Plan
+
+## Objective
+
+Measure and document the performance improvements from incremental rendering, providing concrete numbers for the PR.
+
+## Metrics to Measure
+
+1. **Render Time** (seconds)
+2. **Peak Memory Usage** (MB)
+3. **Files Processed** (count)
+4. **Files Skipped** (incremental only)
+
+## Test Scenarios
+
+| Scenario | Description | Expected Improvement |
+|----------|-------------|---------------------|
+| Cold Render | First render, no cache | Baseline (similar) |
+| Warm Render | Re-render, no changes | Major (skip all) |
+| Partial Change | 1-2 files modified | Significant (skip most) |
+| Config Change | guides.xml modified | None (full re-render) |
+
+## Test Documentation Projects
+
+1. **Small**: `Documentation/` (14 files) - quick validation
+2. **Medium**: `Documentation-rendertest/` (~50 files) - included in repo
+3. **Large**: External TYPO3 docs (e.g., reference-coreapi) - real-world test
+
+## Implementation Options
+
+### Option A: Standalone Benchmark Script
+```bash
+./benchmark.sh [branch] [scenario]
+```
+- Simple bash script with `time` and memory tracking
+- Runs in Docker for reproducibility
+- Outputs CSV/JSON for comparison
+
+### Option B: PHPUnit Performance Tests
+- `@group benchmark` tests
+- Use PHPUnit's `assertLessThan` for regression detection
+- Integrated with CI (can be slow)
+
+### Option C: Makefile Targets
+```make
+make benchmark-cold
+make benchmark-warm
+make benchmark-compare
+```
+- Uses existing Docker setup
+- Easy to run manually
+- Outputs formatted report
+
+## Recommended Approach: Hybrid (A + C)
+
+1. **Makefile targets** for easy execution
+2. **Bash script** for actual measurement logic
+3. **Docker container** for reproducibility
+4. **JSON output** for programmatic comparison
+5. **Markdown report** for PR documentation
+
+## Benchmark Script Design
+
+```
+benchmark/
+├── run-benchmark.sh      # Main benchmark runner
+├── compare-branches.sh   # Compare main vs feature
+├── scenarios/
+│   ├── cold.sh          # Cold render scenario
+│   ├── warm.sh          # Warm render (re-run)
+│   └── partial.sh       # Modify file, re-render
+└── results/
+    └── .gitkeep
+```
+
+## Measurements Approach
+
+### Time Measurement
+```bash
+/usr/bin/time -v ./vendor/bin/guides ... 2>&1
+# Extract: "Elapsed (wall clock) time"
+```
+
+### Memory Measurement
+```bash
+# From /usr/bin/time -v output:
+# "Maximum resident set size (kbytes)"
+```
+
+### PHP-level Metrics
+```php
+$start = hrtime(true);
+// ... render ...
+$elapsed = (hrtime(true) - $start) / 1e9;
+$memory = memory_get_peak_usage(true);
+```
+
+## Output Format
+
+### JSON (machine-readable)
+```json
+{
+  "branch": "feature/php-8.5-only",
+  "scenario": "warm",
+  "project": "Documentation-rendertest",
+  "metrics": {
+    "time_seconds": 2.34,
+    "memory_mb": 128.5,
+    "files_total": 51,
+    "files_rendered": 0,
+    "files_skipped": 51
+  }
+}
+```
+
+### Markdown (for PR)
+```markdown
+| Scenario | main | feature | Improvement |
+|----------|------|---------|-------------|
+| Cold     | 5.2s | 5.1s    | ~2%         |
+| Warm     | 5.2s | 0.8s    | 85%         |
+| Partial  | 5.2s | 1.2s    | 77%         |
+```
+
+## Execution Plan
+
+### Phase 1: Create Benchmark Infrastructure
+- [ ] Create `benchmark/run-benchmark.sh`
+- [ ] Add Makefile targets
+- [ ] Test with local Documentation/
+
+### Phase 2: Measure Current Branch
+- [ ] Run cold/warm/partial scenarios
+- [ ] Record results in JSON
+
+### Phase 3: Compare with Main
+- [ ] Checkout main, run same scenarios
+- [ ] Generate comparison report
+
+### Phase 4: Add to PR
+- [ ] Include benchmark results in PR description
+- [ ] Add benchmark scripts to repo (optional)
+
+## Docker Command Template
+
+```bash
+docker run --rm \
+  -v $(pwd):/project \
+  -w /project \
+  ghcr.io/typo3-documentation/render-guides:latest \
+  /usr/bin/time -v \
+  ./vendor/bin/guides \
+    --no-progress \
+    --output=/tmp/output \
+    Documentation-rendertest
+```
+
+## Notes
+
+- Run multiple times (3-5) and average for accuracy
+- Clear caches between cold runs
+- Use same hardware/container for fair comparison
+- Document system specs in results

Dockerfile

@@ -1,23 +1,43 @@
-FROM php:8.1-cli-alpine AS builder
+FROM php:8.5-cli-alpine AS builder
 
 COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie
 COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
 
-RUN apk add --update $PHPIZE_DEPS
+RUN apk add --update $PHPIZE_DEPS patch git
 RUN pie install arnaud-lb/inotify && docker-php-ext-install pcntl
 
 WORKDIR /opt/guides
 COPY . /opt/guides
 
-RUN composer install --no-dev --no-interaction --no-progress  \
+RUN composer install --no-dev --no-interaction --no-progress \
     --no-suggest --optimize-autoloader --classmap-authoritative
 
-FROM php:8.1-cli-alpine
+# Apply performance patches for guides-restructured-text
+# Use --forward to skip already-applied hunks, --reject-file=/dev/null to suppress reject files
+RUN cd /opt/guides/vendor/phpdocumentor/guides-restructured-text && \
+    patch -p1 --forward --reject-file=/dev/null < /opt/guides/patches/inline-parser-lexer-reuse.patch || true && \
+    patch -p1 --forward --reject-file=/dev/null < /opt/guides/patches/line-checker-cache.patch || true && \
+    patch -p1 --forward --reject-file=/dev/null < /opt/guides/patches/buffer-unindent-cache.patch || true && \
+    patch -p1 --forward --reject-file=/dev/null < /opt/guides/patches/inline-lexer-regex-cache.patch || true && \
+    patch -p1 --forward --reject-file=/dev/null < /opt/guides/patches/field-list-regex-cache.patch || true && \
+    patch -p1 --forward --reject-file=/dev/null < /opt/guides/patches/directive-rule-regex-cache.patch || true && \
+    patch -p1 --forward --reject-file=/dev/null < /opt/guides/patches/enumerated-list-regex-cache.patch || true && \
+    patch -p1 --forward --reject-file=/dev/null < /opt/guides/patches/link-rule-regex-cache.patch || true && \
+    patch -p1 --forward --reject-file=/dev/null < /opt/guides/patches/grid-table-rule-regex-cache.patch || true && \
+    patch -p1 --forward --reject-file=/dev/null < /opt/guides/patches/simple-table-rule-regex-cache.patch || true
+
+# Apply performance patches for guides
+RUN cd /opt/guides/vendor/phpdocumentor/guides && \
+    patch -p1 --forward --reject-file=/dev/null < /opt/guides/patches/external-reference-resolver-cache.patch || true
+
+FROM php:8.5-cli-alpine
 
 COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie
 RUN apk add --update $PHPIZE_DEPS
 RUN pie install arnaud-lb/inotify && docker-php-ext-install pcntl
 
+# Install GNU time for benchmarking (busybox time doesn't support -v)
+RUN apk add --no-cache time
 RUN apk del $PHPIZE_DEPS && rm -rf /var/cache/apk/* /tmp/* /usr/share/php/* /usr/local/lib/php/doc/* /usr/local/lib/php/test/*
 
 COPY . /opt/guides
@@ -26,6 +46,8 @@ WORKDIR /opt/guides
 COPY --from=builder /opt/guides/vendor /opt/guides/vendor
 RUN echo "memory_limit=4G" >> /usr/local/etc/php/conf.d/typo3.ini
 RUN echo "error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT" >> /usr/local/etc/php/conf.d/typo3.ini
+RUN echo "opcache.enable_cli=1" >> /usr/local/etc/php/conf.d/typo3.ini
+RUN echo "opcache.interned_strings_buffer=16" >> /usr/local/etc/php/conf.d/typo3.ini
 
 ARG TYPO3AZUREEDGEURIVERSION
 ENV TYPO3AZUREEDGEURIVERSION=$TYPO3AZUREEDGEURIVERSION