Download the PHP package huncwotdev/twigflow without Composer

TwigFlow

TwigFlow is a PHP rendering layer that sits between a headless CMS (Sanity or Payload) and the browser. It fetches content from the CMS, runs it through optional PHP processors, and renders it using Twig templates.

Think of it as a "glue" application: the CMS holds all your content, your Twig templates define how pages look, and TwigFlow connects them — handling routing, caching, search, and multi-language support along the way.

How a Page Request Works

Connecting to a CMS

The CMS is selected via the CMS_CLIENT environment variable. Two clients are available out of the box.

Sanity

Set CMS_CLIENT=sanity and provide:

TwigFlow talks to Sanity using GROQ queries. Examples of what it fetches:

What gets processed automatically:

• localeString / localeText — multi-language fields; TwigFlow picks the value for the active language
• blockContent / localeBlockContent — Sanity's Portable Text; converted to HTML
• reference — resolved by fetching the referenced document and substituting it inline
• sanity.imageAsset — image URL constructed from the Sanity CDN

Reference resolution is configured in application/reference_fields.json. It tells TwigFlow which fields to fetch when it encounters a reference:

Payload CMS

Set CMS_CLIENT=payload and provide:

TwigFlow fetches pages via the Payload REST API:

Payload uses Lexical for rich text. TwigFlow parses the Lexical JSON format into HTML, handling paragraphs, headings, bold/italic/underline, lists, blockquotes, and links.

Directory Structure

Configuration

All configuration lives in a .env file in the project root.

Required

Optional

Sanity-specific

Database (optional, for scraper queue)

Routing

Routes are defined in src/Config/routes.php. Built-in routes:

Collection routes are defined in application/routes.json:

This maps /blog/my-post to the blog collection in the CMS, rendered with application/views/pages/blog.twig.

Language routing is automatic. If SUPPORTED_LANGUAGES=en,pl, then /en/about and /pl/about both resolve to the about page with the appropriate language active.

The Module System

Pages in the CMS are built from modules — named blocks of content. TwigFlow processes each module and makes the data available to Twig.

For simple modules (static content), no PHP code is needed. For modules that require extra data (e.g., a "Latest Articles" module that needs to fetch recent posts), you create a processor in application/modules/m_{type}.php:

The fetchData() return values are fired as parallel HTTP requests. Once all requests settle, process() receives the results. This keeps page load times low even when a page has many data-hungry modules.

Global Data

Data you need on every page (navigation, footer, site settings) is defined in application/globals.json:

These queries run alongside module queries and are available in every Twig template as {{ globals.navigation }}.

Templates and the HtmlUpdater

Templates live in application/views/. The default template for all pages is page.twig. Collection-specific templates go in pages/ (e.g., pages/blog.twig).

Every template receives this data:

After Twig renders, HtmlUpdater scans the HTML for special placeholders:

Search

TwigFlow includes a search system built on top of Sanity's scraped_documents collection.

How content gets indexed

1. GET /api/scraper/init — Compares all CMS documents against the existing search index and creates a job for each new or updated document.
2. GET /api/scraper/process — Processes pending jobs: renders each page, extracts text from the <article> element (skipping elements with class no-search), and saves the cleaned text to Sanity as a scraped_documents record.
3. GET /api/scraper/prune — Deletes search index entries for documents that no longer exist in the CMS.

Search endpoints

Full search — GET /api/search?q=query Returns results with highlighted snippets, sorted by relevance (title matches first).

Live search — GET /api/live-search?q=query Returns fewer results with smaller snippets; designed for autocomplete.

Response format:

To exclude content from search indexing, add class="no-search" to any HTML element in your templates.

Caching

TwigFlow has three caching layers:

Caching is automatically disabled when APP_ENV=development.

To bypass the cache on a single request, add ?disable_cache=true to the URL.

To clear all caches (and optionally pre-warm specific paths), call GET /api/clear-cache. Paths to pre-warm are listed in application/cache_regeneration.json.

Multi-Language Support

Set SUPPORTED_LANGUAGES=en,pl,de to enable multilanguage routing.

• Language is detected from the URL prefix (/en/, /pl/), then from the session, then from the Accept-Language header, then from DEFAULT_LANGUAGE.
• Sanity localeString fields are automatically resolved to the active language.
• Bots (Googlebot, Bingbot, etc.) receive 301 redirects; regular users get 302 redirects to avoid locking the browser's back button.
• Every page render includes a paths variable with the current page's URL in each supported language, for use in a language switcher.

Custom API Endpoints

Drop a PHP file into application/api/{method}/{endpoint}.php and TwigFlow will route GET/POST /api/{endpoint} to it automatically:

Installation

TwigFlow is a Composer package. The recommended way to start a new project is with the boilerplate, which gives you the application/ directory scaffold and a working index.php entry point:

1. Clone the boilerplate:

2. Install TwigFlow and its dependencies via Composer:

3. Create a .env file in the project root and fill in your CMS credentials (see Configuration above).

4. Point your web server document root at the project root. The included .htaccess routes all requests through index.php.

Requirements: PHP 8.2+, Composer, a web server with mod_rewrite (Apache) or equivalent.

If you are adding TwigFlow to an existing project rather than using the boilerplate, require the package the same way (composer require huncwotdigital/twigflow) and then create the application/ directory structure manually as described in Directory Structure above.