Contao Page-and-Article Architecture: Boundaries, Caching, and Operational Limits

Requirements Driving the Design

Contao's page-and-article system solves a specific problem: content editors need to structure information independently from site navigation. A marketing team might reorganize the menu weekly while the legal disclaimer article stays pinned to the footer across every page. The architecture decouples where content lives (articles) from where visitors navigate (pages).

The smallest suitable design stores pages in a recursive adjacency list (tl_page) and articles in a flat table (tl_article) with a foreign key to their owning page. This avoids the overhead of nested sets or closure tables while keeping the schema simple enough for direct SQL inspection.

Trust and Data Boundaries

Permission enforcement happens at the page branch level. When a backend user is assigned to a page mount, the ACL layer injects a WHERE pid IN (...) clause into every query touching tl_article, tl_content, or tl_module. The boundary is coarse: you cannot restrict a single article without moving it to its own page branch.

Custom PHP hooks (loadDataContainer, getPages) run with full database credentials. A poorly written hook can bypass the mount restriction by issuing raw queries. Treat hook directories as privileged code — audit them like you would middleware.

Rendering and the Template Boundary

The frontend controller fetches the page record, resolves its layout, loads assigned articles, then passes a read-only data array to Twig templates. The template receives no database handles, no service container, and no request object — only structured arrays. This boundary prevents template authors from triggering N+1 queries or mutating state.

Example fragment from a typical page.html5 template:

{% for article in page.articles %}
  {% include '@ContaoCore/article_default.html.twig' with { article: article } %}
{% endfor %}

The article variable contains pre-hydrated content elements (tl_content rows) grouped by column. No lazy loading occurs inside the template.

Caching Layer and Operational Checks

Contao caches rendered page fragments in tl_cache keyed by page ID, language, and a hash of the member group context. The cache key does not include article modification timestamps — invalidation relies on the purgeCache hook fired after any data container save.

Run this diagnostic on a staging server to measure cache effectiveness:

# Run from Contao root (requires CLI access)
php vendor/bin/contao-console debug:cache --group=page
php vendor/bin/contao-console doctrine:query:sql "SELECT COUNT(*) FROM tl_cache WHERE group='page'"

Expected check: the fragment count should roughly equal (pages × languages × member group combinations). A count orders of magnitude higher indicates cache fragmentation — often caused by per-user cache keys from a misconfigured module.

Enable the debug toolbar ($GLOBALS['TL_CONFIG']['debugMode'] = true; in system/config/localconfig.php) and watch the query count on a cold page load. A healthy page with 5 articles and 20 content elements should execute 12–18 queries. Anything above 40 suggests missing indexes or a runaway hook.

Failure Modes

Cache Inconsistency

When multiple editors save articles concurrently, the purgeCache hook fires per-save. If editor A saves article 1 (purges page cache) and editor B saves article 2 (purges again) within the same second, the second purge may delete the fragment that editor A's request just rebuilt. Visitors see stale content for the cache TTL (default 24 hours).

Mitigation: set $GLOBALS['TL_CONFIG']['cacheLifetime'] = 3600; during heavy editing windows, or implement a deployment-time cache warm script that rebuilds critical pages after bulk imports.

Database Deadlocks

The adjacency list uses SELECT ... FOR UPDATE when moving page branches to prevent tree corruption. Under high concurrency (e.g., a script reorganizing 500 pages while editors save articles), InnoDB deadlocks appear as SQLSTATE[HY000]: General error: 1213 Deadlock found.

Verification: enable MySQL's innodb_print_all_deadlocks=ON and check the error log. The smallest fix is serializing structural changes — run tree moves via a maintenance window or a queue worker with a single consumer.

Recursive Menu Degradation

The menu builder (Contao\Menu\MenuBuilder) walks the page tree recursively in PHP. A 1,000-page tree with 6 levels of nesting takes ~120 ms on a modern CPU; at 5,000 pages it exceeds 800 ms and triggers PHP's max_execution_time on shared hosting.

Concrete check: run EXPLAIN SELECT * FROM tl_page WHERE pid=0 ORDER BY sorting and verify the index on pid,sorting is used. If the query scans, add the composite index. For sites exceeding 3,000 pages, consider a materialized path column (path VARCHAR(255)) populated by a hook on page save — this flattens menu generation to a single LIKE 'root/%' query.

Conditions That Would Change the Design

The current architecture assumes server-side rendering with session-bound permissions. Three conditions force a redesign:

1. Headless delivery: The page tree becomes a content graph exposed via API. The tl_page adjacency list works for REST endpoints but requires a GraphQL resolver that can traverse relationships without N+1 queries — typically solved by adding a children connection with DataLoader batching.
2. Fine-grained article permissions: If editors need per-article ACLs without page mounts, the foreign key tl_article.pid stops being the sole permission anchor. You would add a join table tl_article_permission and modify the query builder's addPermissionFilters() method.
3. Edge rendering: Moving fragment assembly to a CDN edge worker means the cache key must be derivable from the request alone (no session). Replace member-group hashing with a signed JWT claim or a cookie-based segment identifier.

Verification Checklist for New Deployments

• Inspect tl_page and tl_article row counts; confirm pid foreign keys are indexed.
• Create a backend user with a single page mount; verify they cannot see articles outside that branch in the article list module.
• Load the homepage with debug toolbar enabled; confirm query count stays under 25 for a typical page.
• Simulate concurrent saves: open two browser sessions, edit different articles on the same page, save within 2 seconds. Check that the frontend shows both changes after cache TTL expires.
• Run php vendor/bin/contao-console cache:clear --no-warmup on the production hardware; monitor CPU. If it spikes above 80% for >10 seconds, plan cache warming during deployments.

Limitations

This analysis covers Contao 4.13/5.x LTS behavior. The hook system and cache internals differ in 4.9 and earlier. The recursive menu performance threshold assumes PHP 8.1+ with JIT disabled; JIT can reduce the 5,000-page walk to ~400 ms but adds warm-up variance. Cache inconsistency scenarios assume default file-based or database cache; Redis/Memcached backends change the race window but not the fundamental invalidation model.