# Migration Guide: v13.1.0 Fluid Templates Refactoring

## Overview

Version 13.1.0 introduces a modern service-based architecture using TYPO3 v13 ViewFactoryInterface and Fluid templates. The old controller-based approach has been replaced with a new adapter that uses the service architecture internally.

## For 99.9% of Users: No Action Required ✅

If you are using this extension without any custom PHP code or XCLASS, **you don't need to do anything**. Everything continues to work exactly as before.

The internal architecture has been modernized, but the TypoScript interface remains the same.

## Breaking Changes

### v13.1.0: Internal Architecture Migration
- Old controllers (`ImageRenderingController`, `ImageLinkRenderingController`) removed
- New `ImageRenderingAdapter` uses service architecture internally
- TypoScript configuration unchanged
- Template overrides via Fluid templates now possible

## For Advanced Users: Migration Path

### If You Extended Controllers (XCLASS)

**Old Approach (v13 and earlier):**
```php
// ext_localconf.php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['Objects'][\Netresearch\RteCKEditorImage\Controller\ImageRenderingController::class] = [
    'className' => \Vendor\Extension\XClass\CustomImageRenderingController::class
];

// CustomImageRenderingController.php
class CustomImageRenderingController extends \Netresearch\RteCKEditorImage\Controller\ImageRenderingController
{
    public function renderImageAttributes(?string $content, array $conf, ServerRequestInterface $request): string
    {
        // Custom logic
        return parent::renderImageAttributes($content, $conf, $request);
    }
}
```

**✅ Recommended: Override Fluid Templates Instead**

Create your own Fluid templates in your site package:

```
your-sitepackage/
├── Resources/
│   └── Private/
│       └── Templates/
│           └── RteCKEditor/
│               └── Image/
│                   ├── Standalone.html
│                   ├── WithCaption.html
│                   └── ... (override as needed)
```

Register your template paths in TypoScript:
```typoscript
lib.parseFunc_RTE.tags.img {
    preUserFunc = Netresearch\RteCKEditorImage\Service\ImageRenderingService->render
    templateRootPaths.100 = EXT:your_sitepackage/Resources/Private/Templates/RteCKEditor/
}
```

### If You Need Custom Business Logic

**New Approach: Event Listeners (PSR-14)**

```php
// Configuration/Services.yaml
services:
  Vendor\Extension\EventListener\CustomImageProcessing:
    tags:
      - name: event.listener
        identifier: 'custom-image-processing'
        event: Netresearch\RteCKEditorImage\Event\BeforeImageRenderingEvent

// EventListener/CustomImageProcessing.php
namespace Vendor\Extension\EventListener;

use Netresearch\RteCKEditorImage\Event\BeforeImageRenderingEvent;

class CustomImageProcessing
{
    public function __invoke(BeforeImageRenderingEvent $event): void
    {
        $dto = $event->getImageData();

        // Modify DTO before rendering
        $event->setImageData(new ImageRenderingDto(
            src: $dto->src,
            width: $dto->width * 2, // Example: double width
            // ... other properties
        ));
    }
}
```

**Note:** PSR-14 events will be added in Phase 3 of the implementation.

## For Template Developers

### Old HTML Output (v13)
Generated by PHP string concatenation in controllers.

### New HTML Output (v14+)
Generated by Fluid templates with full override capability.

**Example: Custom Caption Styling**

```html
<!-- your-sitepackage/Resources/Private/Templates/RteCKEditor/Image/WithCaption.html -->
<figure class="image{f:if(condition: image.htmlAttributes.class, then: ' {image.htmlAttributes.class}')}">
    <img src="{image.src}"
         alt="{image.alt}"
         width="{image.width}"
         height="{image.height}"
         f:if="{image.title}" title="{image.title}" />
    <figcaption class="custom-caption-style">
        <span class="caption-icon">📷</span>
        {image.caption}
    </figcaption>
</figure>
```

## Technical Architecture Changes

### Old Architecture (v13)
```
TypoScript preUserFunc
    ↓
Controller (876 lines)
    ↓
String concatenation
    ↓
HTML output
```

### New Architecture (v14+)
```
TypoScript preUserFunc
    ↓
ImageAttributeParser (HTML → attributes)
    ↓
ImageResolverService (Business logic + security)
    ↓
ImageRenderingService (ViewFactoryInterface)
    ↓
Fluid Template
    ↓
HTML output
```

## Security Preservation

All existing security measures are preserved:

- ✅ **File Visibility Validation:** `validateFileVisibility()` prevents privilege escalation
- ✅ **XSS Prevention:** Caption sanitized with `htmlspecialchars(ENT_QUOTES | ENT_HTML5)`
- ✅ **ReDoS Protection:** DOMDocument parsing instead of vulnerable regex
- ✅ **Type Safety:** Readonly DTO properties enforce type correctness

## TypoScript Configuration

### No Changes Required (v13.1.0)

Your existing TypoScript continues to work. The extension automatically configures:

```typoscript
lib.parseFunc_RTE {
    tags.img {
        preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingAdapter->renderImageAttributes
    }
    tags.a {
        preUserFunc = Netresearch\RteCKEditorImage\Controller\ImageRenderingAdapter->renderInlineLink
    }
}
```

The new `ImageRenderingAdapter` internally uses the modern service architecture while maintaining full backward compatibility with the TypoScript interface.

## Common Questions

### Q: Will my images stop working after upgrading to v13.1.0?
**A:** No. Everything works exactly as before. The internal implementation has changed but the interface remains identical.

### Q: Do I need to change my TypoScript?
**A:** No. Existing TypoScript configuration is fully supported.

### Q: What if I extended the old controllers with XCLASS?
**A:** The old controllers have been removed in v13.1.0. You should migrate to Fluid template overrides (recommended) or use the new service architecture directly.

### Q: Can I customize the HTML output?
**A:** Yes! Override Fluid templates in your site package (see "Override Fluid Templates" section above).

## Timeline

| Version | Release | Status | Action Required |
|---------|---------|--------|----------------|
| v13.0.x | Previous | Legacy controller architecture | None |
| v13.1.0 | 2025 Q1 | Modern service architecture | None (automatic) |

## Support

If you have questions about migration:

1. Check this guide first
2. Read the RFC: `Documentation/Architecture/RFC-Fluid-Templates-Refactoring.md`
3. Open a GitHub issue: https://github.com/netresearch/t3x-rte_ckeditor_image/issues
4. Search existing issues for similar questions

## Additional Resources

- **RFC Document:** `Documentation/Architecture/RFC-Fluid-Templates-Refactoring.md`
- **Security Checklist:** `Documentation/Architecture/Security-Validation-Checklist.md`
- **TYPO3 ViewFactoryInterface:** https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/13.3/Feature-104773-GenericViewFactory.html
- **Issue #399:** https://github.com/netresearch/t3x-rte_ckeditor_image/issues/399