smnandre/twigdoc

Documentation and validation tool for Twig templates

v0.9.0 2025-12-13 22:44 UTC

Requires

• php: >=8.3
• symfony/console: ^6.0 || ^7.0
• twig/twig: ^3.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^12.0
• symfony/var-dumper: ^6.0 || ^7.0

MIT

• Simon André

README

Document Twig templates, validate their inputs early, and ship confident UI changes.

         

TwigDoc is a zero-config companion for Twig projects. It extracts @var annotations, turns them into documentation, and lets you fail fast by validating template contexts during development, CI, or custom tooling.

Features

Write documentation where it matters

: Keep @block, @var, nullable hints, and array shapes beside the Twig markup they describe.

Generate shareable documentation

: Build HTML or Markdown portals from annotations with twigdoc generate, complete with search, folder trees, and placeholder coverage tracking.

Validate template inputs early

: TwigDoc::validate() and the twigdoc validate command compare runtime data to the declared contract so CI or local dev trips on missing fields before reviewers do.

Install

composer require smnandre/twigdoc

The CLI lives in vendor/bin/twigdoc; the PHP API is namespaced under TwigDoc\.

Usage

Generate Reports: twigdoc generate

Turn annotations into HTML or Markdown docs for your team:

vendor/bin/twigdoc generate templates/ --output=docs --format=html --include-empty -vv
open docs/index.html

HTML output

• docs/index.html – a single-page app with a folder tree, responsive layout, and Cmd/Ctrl + K search.
• docs/twigdoc_data.js – the structured dataset (window.TWIGDOC_DATA) powering the SPA.

Markdown output

• docs/index.md – a master index with descriptions, variable counts, and links.
• Per-template Markdown files mirroring the template tree (docs/user/profile.md, etc.) so you can commit documentation next to source.

Validate Templates: twigdoc validate

Fail fast when runtime context deviates from the documented contract:

use TwigDoc\TwigDoc;

TwigDoc::validate(__DIR__.'/templates/user/profile.twig', [
    'username' => 'Ada Lovelace',
    'bio' => null,
    'products' => [],
]);

vendor/bin/twigdoc validate templates/

Show Template Docs: twigdoc show

Inspect the parsed documentation for a single template during reviews or pairing:

vendor/bin/twigdoc show templates/user/profile.twig

Documentation

Doc blocks

{#
 # @block User profile
 # @var string $username Display name
 # @var ?string $bio Optional bio
 # @var Product[] $products Purchased products
 #}
<h1>{{ username }}</h1>

Reference

Directive	Example	Meaning
@var <type> $name [description]	@var string $title Page title	Declares a documented variable using PHP-style types.
Nullable types	@var ?string $bio	Allows null or omission; non-nullables must exist in runtime context.
Arrays	@var Item[] $items	Expects an array where every entry matches the inner type.
Scalars	string, int, float, bool (aliases integer, double, boolean).	Primitives follow PHP naming.
@block ...	@block Product detail page	Adds human-friendly copy for docs and search indices.
Descriptions	@var int $age User age in years	Optional free text surfaced in HTML/Markdown outputs.

Anything without annotations is ignored unless you pass --include-empty, which creates placeholder docs for coverage tracking.

Contributing

Contributions, bug reports, and RFCs are welcome! Please open issues or pull requests.

Licence

TwigDoc is released under the MIT Licence. See LICENSE for details.