Fluid Documentation Generator Laravel Package

Technical Evaluation

Verdict: low fit for a Laravel-centric portfolio. Proceed only with a narrow, explicitly bounded use case.

• Architecture fit. The package is a build-time CLI code generator, not a runtime library. It has no service provider, no config publish, no facade, no HTTP surface — nothing a Laravel application would autoload or boot. It scans Fluid ViewHelper classes via Fluid's ViewHelperFinder (Fluid ≥2.12, with 4.4.0 adding Fluid 4.0 support), emits a directory tree of RST files plus a per-namespace JSON metadata file, and expects those artifacts to be rendered by render-guides. A Laravel codebase contains Blade components and PHP classes, not Fluid ViewHelpers; on a pure Laravel stack the tool would find zero inputs and produce an empty scaffold. There is no adapter path.
• Integration feasibility. Mechanically trivial where applicable: composer req --dev, one CLI invocation, JSON configs validated against a published schema, wildcards supported, output redirected with FLUID_DOCUMENTATION_OUTPUT_DIR. Hard structural constraint: it must be installed inside the Composer project that physically contains the ViewHelper source. A repo that only consumes ViewHelpers from vendor/ cannot use it meaningfully. That rules out most Laravel services as hosts and rules in only TYPO3 extension repos or Fluid Standalone projects.
• Technical risk. High on adoption, low on runtime. Adoption risk: 1 star, 0 dependents, a changelog dominated by one or two contributors, and a 4.0.0 rewrite that changed the entire generation model (config format, template-based output). Expect breaking changes across majors and no community backstop when something breaks — budget for reading source. Runtime risk is near zero because it executes in CI/dev only and never ships to production. Secondary risk: the output is coupled to render-guides' proprietary RST directive, so we inherit the rendering pipeline's version constraints as well as this package's.
• Licensing. LGPL-3.0 is normally acceptable for a --dev build tool that is not distributed or linked into a shipped binary; confirm against our policy, since LGPL in the dependency graph occasionally triggers legal review regardless of usage mode.
• Key questions to resolve before committing.
  1. Do we actually own Fluid ViewHelper source anywhere, or is this purely a Laravel estate? If the latter, stop here.
  2. If yes — is our docs target RST/Sphinx/render-guides, or Markdown/HTML? RST-first output means any other target is conversion work we own.
  3. What is the ViewHelper count? Below roughly a few dozen across one package, config and CI wiring cost more than manual upkeep.
  4. Who owns the render-guides pipeline, and can we pin a compatible version?
  5. Is there a fallback plan if maintenance stalls — fork, or hand-rolled generator?

Integration Approach

• Stack fit. Assume non-fit for Laravel/Blade/Symfony-Twig estates; there is no general-purpose value to extract. The realistic integration is a TYPO3 extension or Fluid Standalone library that we maintain, feeding a docs site we already render with Sphinx or render-guides. If we have no such pipeline, the true cost is standing up render-guides, not adding this package.
• Migration path. Greenfield rather than migration: add as --dev, author one JSON config per package (name, namespace alias, target namespace), run the CLI against each, and place output under the docs source tree. If we currently hand-maintain ViewHelper reference pages, the sequence is: generate → diff against existing pages → reconcile gaps (cross-references, anchors, custom prose) → cut over → delete the manual pages. Do not run both in parallel longer than one release cycle.
• Compatibility gates. PHP ≥8.0 (7.4 dropped at 3.0.0), Fluid ≥2.12 for ViewHelperFinder, Fluid 4.0 supported from 4.4.0, and justinrainbow/json-schema version-constrained (^6.8 permitted in 4.4.3). These are the pins to lock and test in CI. Pin the generator by minor range and treat majors as planned work.
• Sequencing.
  1. Spike: run against one real ViewHelper package, confirm output renders in our existing docs toolchain. This is the go/no-go gate and should take days, not weeks.
  2. Wire a single non-blocking CI job publishing to a preview location; measure output quality and reviewer effort on the diff.
  3. Add the remaining packages as additional config files in index order — this ordering is the docs navigation IA, so decide it deliberately rather than alphabetically by accident.
  4. Promote to a release gate only after two clean cycles. Documentation freshness as a merge gate is a policy decision, not a technical one; make it explicitly.
  5. Defer localization and any Markdown/HTML target; both require a layer we would own.

Operational Impact

• Maintenance. Low steady-state effort, concentrated in three places: version pins (PHP, Fluid, JSON-schema), template overrides when default RST output does not match house style, and reviewing generated diffs so genuine prose edits are not clobbered. Treat the generated tree as build output — do not hand-edit it, or the next run overwrites the work.
• Support. No vendor SLA, no commercial backing, single-org stewardship (TYPO3 Documentation). Support model is "read the source and file an issue." Assign one named engineer as owner with authority to fork. Absent that, adoption quietly rots after the first breaking change.
• Scaling. Scales well linearly across packages — one config file each, one invocation, deterministic ordering (ViewHelpers sorted for consistent output since 4.3.0). It does not scale across languages or frameworks; each new non-Fluid stack needs its own tool. Failure to plan for that produces a docs estate with one working pipeline and N hand-maintained islands.
• Failure modes to instrument.
  • Empty or partial output when a ViewHelper cannot be discovered (namespace alias or target namespace misconfigured) — the generator succeeds while silently omitting pages. Assert on expected page count in CI, not just exit code.
  • Render breakage downstream when render-guides and the generator drift; the JSON contract is implicit, not versioned at the artifact level.
  • Config schema validation failures surfacing only at build time; validate configs in the same PR that changes them.
  • Upstream Fluid changes breaking ViewHelperFinder reflection — this is the most likely cause of a hard stop.
  • Overwrites of manual edits in output directories; enforce a generated-code marker and a lint rule.
• Ramp-up. For a TYPO3-fluent engineer: under a day to first successful generation, a few days to confident ownership including templates and CI. For a Laravel-only team: the ramp is not on this tool but on Fluid, RST, and render-guides — weeks, with no transferable payoff to the Laravel estate. That asymmetry is the decisive operational fact and should drive the recommendation toward "decline" unless a real Fluid codebase exists. If the strategic intent is auto-generated component reference for Blade, treat this package as a design precedent only and budget a separate, purpose-built generator.