Fluid Documentation Generator Laravel Package

Getting Started

Start with the honest framing: this is not a Laravel package. There is no service provider, no config/fluid-documentation.php, no facade, no Blade integration. It ships a single CLI binary (vendor/bin/fluidDocumentation) that reflects over PHP classes implementing Fluid's ViewHelperInterface (via Fluid's ViewHelperFinder, introduced in Fluid 2.12). Run it inside a plain Laravel app and it will happily install and happily find nothing, because Laravel has no Fluid ViewHelpers.

So the practical entry points for a Laravel developer are narrow and specific:

1. You also maintain TYPO3 extensions (a common shop arrangement: Laravel for product APIs, TYPO3 for a client's content site). This tool documents the TYPO3 half.
2. You are building an in-house Fluid-style tag/component library and want the metadata-plus-RST reference model rather than inventing one.
3. You are evaluating documentation-generation architecture and want to see how a mature org derives reference docs from reflection.

Installation, once you are in that situation:

composer require --dev t3docs/fluid-documentation-generator

Requirements: PHP 8.1+ (7.4 dropped in 3.0.0), Fluid 2.12+ (4.x supported as of 4.4.0). Critically, it must be installed inside the composer project that actually contains the ViewHelper classes — not in a consuming app that only pulls them from vendor/.

Where to look first, in this order:

• src/Config.schema.json in the installed package — this is the real API surface. Everything else is commentary.
• config/typo3/* and config/fluidStandalone/* — working, battle-tested example configs.
• The README, which covers the rest.

Minimal first run:

{
  "name": "MyPackage",
  "namespaceAlias": "my",
  "targetNamespace": "http://typo3.org/ns/Vendor/MyPackage/ViewHelpers"
}

vendor/bin/fluidDocumentation generate mypackage.json

Output lands in fluidDocumentationOutput/: <Name>/Index.rst, one .rst per ViewHelper, a top-level Index.rst, and <Name>.json containing all extracted metadata.

Implementation Patterns

One JSON config per documented namespace. The CLI takes 1-n config files, and argument order determines index page order. Wildcards work, which makes the pattern for a monorepo:

vendor/bin/fluidDocumentation generate docs/viewhelpers/*.json

Keep configs in your own repo, not in vendor/. The README examples reference vendor/t3docs/.../config/typo3/*, which is fine for a throwaway clone but is a trap in CI — a composer update regenerates vendor/ and your docs pipeline silently disappears. Copy the configs you need into something like Documentation/ViewHelpers/ and own them.

Wire it as a composer script, mirroring how you'd wire an Artisan command:

"scripts": {
    "docs:viewhelpers": "fluidDocumentation generate docs/viewhelpers/*.json"
}

Then composer docs:viewhelpers in CI, after composer install.

Use FLUID_DOCUMENTATION_OUTPUT_DIR to control placement. This is the only supported way to redirect output — there is no --output CLI flag and no output key in the JSON schema. In CI, point it at a build directory; locally, point it wherever your render-guides checkout expects.

Treat output as a build artifact, but commit it if your docs site builds from a repo checkout. render-guides consumes the generated JSON through a dedicated RST directive, so the JSON must be present at render time. The pragmatic split: RST and JSON are generated and committed by a bot job, never hand-edited; the configs are the source of truth.

Drift-gating. Since 4.3.0 the ViewHelpers are sorted for consistent output, which makes the generated tree diffable. That enables the useful pattern: regenerate in CI, git diff --exit-code, fail the build if docs are stale relative to code. This is the single highest-value integration for a team that already runs static analysis on PRs.

If you are Laravel-only, do not bend this package — crib the pattern instead. The transferable idea is "reference documentation is a function of class reflection, generated at build time, schema-validated on input." An Artisan command using phpDocumentor/ReflectionDocBlock over your own component classes gives you the same property without the Fluid dependency.

Gotchas and Tips

• Structural incompatibility is the headline gotcha. The package must live in the same composer project as the ViewHelpers it scans. A Laravel app consuming a TYPO3 package via vendor/ is the wrong topology and will produce empty or partial output.
• RST only. No Markdown, no HTML, no JSON-only mode beyond the metadata sidecar. If your docs portal is Docusaurus/VuePress/GitHub Pages, the conversion work is yours. The JSON file is the escape hatch — consume it with your own renderer.
• Cross-references to TYPO3 docs are commented out by default as of 4.4.1. If you expected working cross-links out of the box, look at the generated RST: the reference is there but disabled, and you have to re-enable it.
• Output directory is environment-variable-only. Two different output targets in one run is not expressible; you need separate invocations with the env var set differently.
• json-schema version surface. 4.4.3 relaxed the constraint to justinrainbow/json-schema ^6.8. In a large Laravel dependency graph that already pins an older json-schema, expect a resolution conflict and budget for it.
• Config validation failures are easy to misread. If the schema passes but output is empty, the usual cause is targetNamespace not matching the actual PHP namespace of the ViewHelper classes, or a Fluid version below 2.12 so ViewHelperFinder isn't available.
• Headline anchors are specifiable since 4.1.0 — use explicit anchors rather than relying on generated slugs if you plan to link into the reference from narrative docs, otherwise a ViewHelper rename breaks inbound links.
• Extension point is the RST templates (the "default templates" work landed in 4.3.0). If the generated page shape doesn't fit your docs theme, override templates rather than post-processing RST with sed.
• Licensing and bus factor. LGPL-3.0 is normally fine for a --dev build tool, but route it through legal if your policy is strict about copyleft anywhere in the dependency graph. One star and zero dependents means you are an early adopter: read the source when something breaks. The offsetting signal is that it is actively released under the TYPO3 Documentation org, so 4.4.x maintenance is real.