Fluid Documentation Generator Laravel Package

Getting Started

Minimal Setup

1. Install the package in your Laravel/TYPO3 project (though primarily TYPO3-focused, it can be adapted for Laravel with Fluid integration):

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

2. Create a basic config file (e.g., viewhelpers_config.json) adhering to the JSON schema:

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

3. Run the generator (adjust paths as needed):

   vendor/bin/fluidDocumentation generate path/to/viewhelpers_config.json
   

   • Outputs to fluidDocumentationOutput/ by default (customizable via FLUID_DOCUMENTATION_OUTPUT_DIR).

4. Render the RST using render-guides or Sphinx.

First Use Case: Documenting a Custom ViewHelper

1. Annotate your ViewHelper with PHPDoc (critical for metadata extraction):

   namespace Vendor\MyLaravelExtension\ViewHelpers;
   
   use TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper;
   
   /**
    * Renders a formatted greeting.
    *
    * = Examples =
    *
    * <code title="Basic">
    * {my:greeting(name: 'John')}
    * </code>
    * <output>
    * Hello, John!
    * </output>
    *
    * @api
    */
   class GreetingViewHelper extends AbstractViewHelper
   {
       public function render(): string
       {
           return 'Hello, ' . htmlspecialchars($this->arguments['name']);
       }
   }
   

2. Generate docs:

   vendor/bin/fluidDocumentation generate viewhelpers_config.json
   

3. Verify output:

   • Check fluidDocumentationOutput/MyLaravelExtension/GreetingViewHelper.rst for auto-generated RST.
   • Use the JSON output (MyLaravelExtension.json) for dynamic rendering (e.g., with render-guides).

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline (GitHub Actions Example)

Add a step to auto-generate docs on main branch pushes or PR merges:

- name: Generate Fluid Documentation
  run: |
    composer require --dev t3docs/fluid-documentation-generator
    vendor/bin/fluidDocumentation generate config/viewhelpers_*.json
    git add fluidDocumentationOutput/
    git diff --quiet || git commit -m "chore: update Fluid docs [skip ci]"

2. Multi-Package Documentation

For Laravel extensions with multiple ViewHelper packages:

# Generate docs for all configs in sequence (order matters for index page)
vendor/bin/fluidDocumentation generate \
  config/viewhelpers_core.json \
  config/viewhelpers_utils.json \
  config/viewhelpers_ui.json

3. Custom Output Directory

Set via environment variable (e.g., in .env or CI):

export FLUID_DOCUMENTATION_OUTPUT_DIR=docs/viewhelpers
vendor/bin/fluidDocumentation generate config/*.json

Laravel-Specific Adaptations

Fluid in Laravel

If using laravel-fluid or similar:

1. Ensure ViewHelpers are in a namespaced directory (e.g., app/ViewHelpers/).
2. Update config to point to Laravel’s autoloaded namespace:

   {
     "name": "LaravelApp",
     "namespaceAlias": "app",
     "targetNamespace": "http://typo3.org/ns/App/ViewHelpers"
   }
   

PHPDoc Annotations

Leverage Laravel’s existing PHPDoc standards for consistency:

/**
 * Renders a paginated list.
 *
 * @param array $items The items to paginate.
 * @param int $perPage Items per page (default: 10).
 * @return string Rendered pagination HTML.
 *
 * @see \Vendor\MyLaravelExtension\ViewHelpers\PaginationViewHelper
 */
class PaginationViewHelper extends AbstractViewHelper

Advanced Patterns

Dynamic Headline Anchors

Force custom anchors for RST links (useful for Laravel’s route-based docs):

{
  "headlineAnchor": "laravel-pagination"
}

Excluding ViewHelpers

Use config to skip internal/undocumented helpers:

{
  "exclude": [
    "Vendor\\MyLaravelExtension\\ViewHelpers\\Internal*"
  ]
}

Template Customization

Override default RST templates (located in vendor/t3docs/fluid-documentation-generator/src/Resources/templates/):

1. Copy templates to config/fluid-documentation-templates/.
2. Update config:

   {
     "templateDir": "config/fluid-documentation-templates/"
   }
   

Gotchas and Tips

Pitfalls

1. PHPDoc Requirements

   • Missing @api tag: ViewHelpers without @api in PHPDoc are ignored. Fix: Add @api to all public ViewHelpers.
   • Incomplete annotations: Missing @param/@return reduces generated metadata. Fix: Use PHPStorm’s PHPDoc generator for quick fixes.

2. Namespace Mismatches

   • Error: No ViewHelpers found in namespace. Cause: targetNamespace in config doesn’t match the PHP namespace. Fix: Verify the namespace in composer.json autoloading and config.

3. RST Rendering Issues

   • Error: Unknown directive 'fluid-viewhelper'. Cause: Missing render-guides or Sphinx extension. Fix: Install render-guides or use a Sphinx extension like sphinxcontrib-fluid.

4. Output Directory Permissions

   • Error: Failed to write to output directory. Fix: Ensure FLUID_DOCUMENTATION_OUTPUT_DIR is writable:

     mkdir -p docs/viewhelpers && chmod -R 777 docs/viewhelpers
     

Debugging Tips

1. Dry Run Mode Use --dry-run to preview changes without writing files:

   vendor/bin/fluidDocumentation generate --dry-run config/*.json
   

2. Verbose Logging Enable debug output:

   vendor/bin/fluidDocumentation generate -v config/*.json
   

3. Validate Config Use the JSON schema validator:

   composer require justinrainbow/json-schema
   vendor/bin/json-schema-validator validate src/Config.schema.json config/viewhelpers_config.json
   

Extension Points

1. Custom Metadata Extraction Extend the generator by subclassing TYPO3\Documentation\Fluid\ViewHelper\ViewHelperFinder and overriding findViewHelpers() to include Laravel-specific logic (e.g., parsing Blade directives).

2. Post-Processing Hooks Use Laravel’s post-autoload-dump event to trigger doc generation:

   // In a service provider
   $this->app->booted(function () {
       Artisan::call('fluidDocumentation:generate', [
           'config' => [base_path('config/viewhelpers.json')],
       ]);
   });
   

3. JSON Output Integration Parse the generated JSON (MyPackage.json) in Laravel for dynamic API docs:

   $viewHelpers = json_decode(file_get_contents(docs_path('MyPackage.json')), true);
   // Use in a controller or Blade component
   

Laravel-Specific Quirks

1. Autoloading ViewHelpers Ensure ViewHelpers are autoloaded in composer.json:

   {
     "autoload": {
       "psr-4": {
         "Vendor\\MyLaravelExtension\\ViewHelpers\\": "app/ViewHelpers/"
       }
     }
   }
   

2. Fluid Standalone in Laravel If using Fluid Standalone, install it as a dev dependency:

   composer require --dev typo3/fluid
   

3. Cross-Referencing Laravel Routes Customize RST templates to link to Laravel’s route names:

   :fluid-viewhelper:`Vendor\\MyLaravelExtension\\ViewHelpers\\GreetingViewHelper`
     <https://laravel-app.test/greeting>