..  include:: /Includes.rst.txt

..  _migration:

=========
Migration
=========

This page lists required migration steps when upgrading to a new version of
the extension.

..  _version-1.1.0:

Version 1.1.0
=============

..  _migration-1.1-process-variables-non-array-data:

Non-array data in `process-variables`
-------------------------------------

If the payload resolved by :ref:`data-processor-process-variables` (e.g. via
:typoscript:`dataSource`) is not an array, the current record's own field
values are no longer used as a fallback. Instead, :typoscript:`variables` are
processed against an empty record, and the payload is provided as the content
object's current value (see :ref:`data-processor-process-variables-payload`).

Variables using :typoscript:`field` in such a configuration now resolve to an
empty value. Either convert the payload to an array beforehand (e.g. using a
:typoscript:`preProcessing` processor), or reference the payload with
:typoscript:`current = 1` instead.

..  _migration-1.1-wrapped-current-values:

Wrapped current values
----------------------

:ref:`data-processor-process-each`, :ref:`data-processor-iterable-to-array`
and :ref:`data-processor-process-variables` now wrap arrays and objects which
cannot be converted to strings in a :php:`CurrentValue` object before providing
them as current value (see :ref:`usage-data-sources-current-wrapped`).
TypoScript is not affected, apart from such values no longer causing errors in
:typoscript:`stdWrap`. Within :typoscript:`stdWrap`, arrays now resolve to a
comma-separated list of their scalar values and stringable objects, all other
wrapped values resolve to an empty string.

Custom PHP code reading :php:`ContentObjectRenderer::getCurrentVal()` within
these processors (e.g. user functions or data source aware processors) must
unwrap the value, see
:ref:`developer-corner-data-source-aware-processor-current-value`.

..  _version-1.0.0:

Version 1.0.0
=============

Version 1.0.0 replaces the previous PHP-class rendering model (DataProcessor /
DataProvider / Presenter) with the :typoscript:`HANDLEBARSTEMPLATE` content
object. All rendering configuration moves to TypoScript; custom PHP classes are
no longer the entry point.

..  _migration-1-removed-classes:

Removed classes and interfaces
--------------------------------

The following classes and interfaces have been removed and have no replacement:

*   :php:`CPSIT\Typo3Handlebars\DataProcessing\DataProcessor` (interface)
*   :php:`CPSIT\Typo3Handlebars\DataProcessing\AbstractDataProcessor`
*   :php:`CPSIT\Typo3Handlebars\Data\DataProvider` (interface)
*   :php:`CPSIT\Typo3Handlebars\Data\Response\ProviderResponse` (interface)
*   :php:`CPSIT\Typo3Handlebars\Presenter\Presenter` (interface)
*   :php:`CPSIT\Typo3Handlebars\Presenter\AbstractPresenter`
*   :php:`CPSIT\Typo3Handlebars\DataProcessing\SimpleProcessor`

The :typoscript:`handlebars.processor` service tag has also been removed.

..  _migration-1-typoscript-entry-point:

TypoScript entry point
-----------------------

**Before:** Each content element was routed to a :php:`DataProcessor` class via
a :typoscript:`USER` content object:

..  code-block:: typoscript

    tt_content.header = USER
    tt_content.header.userFunc = Vendor\Extension\DataProcessing\HeaderProcessor->process

**After:** Use :typoscript:`HANDLEBARSTEMPLATE` directly:

..  code-block:: typoscript

    tt_content.header = HANDLEBARSTEMPLATE
    tt_content.header {
        templateName = Header

        variables {
            header = TEXT
            header.field = header

            subheader = TEXT
            subheader.field = subheader
        }
    }

..  _migration-1-data-preparation:

Data preparation (DataProvider → variables / dataProcessing)
-------------------------------------------------------------

**Before:** Data was prepared in a :php:`DataProvider` class and returned as a
:php:`ProviderResponse` object, which the :php:`Presenter` then passed to the
renderer.

**After:** Data is prepared entirely in TypoScript:

*   Simple field values: use :typoscript:`variables` with content objects
    such as :typoscript:`TEXT`, :typoscript:`FILES`, etc.
*   Database relations and menus: use standard TYPO3 :typoscript:`dataProcessing`
    processors (e.g., :typoscript:`database-query`, :typoscript:`menu`).
*   Per-record variable processing inside a loop: use :ref:`process-variables
    <data-processor-process-variables>`.

..  _migration-1-template-selection:

Template selection (Presenter → templateName)
----------------------------------------------

**Before:** The :php:`Presenter` called :php:`$this->renderer->render('path/to/template', $data)`.

**After:** The template is declared in TypoScript:

..  code-block:: typoscript

    tt_content.my_element {
        templateName = MyElement
    }

For conditional template selection, use stdWrap on :typoscript:`templateName`:

..  code-block:: typoscript

    tt_content.my_element {
        templateName = MyElement
        templateName.override.if {
            isTrue.field = tx_myext_variant
            value = special
        }
        templateName.override = MyElementSpecial
    }

..  _migration-1-helper-registration:

Helper registration
--------------------

**Before:** Helpers were registered via :file:`Services.yaml` tags:

..  code-block:: yaml
    :caption: Configuration/Services.yaml

    services:
      Vendor\Extension\Renderer\Helper\GreetHelper:
        tags:
          - name: handlebars.helper
            identifier: 'greet'
            method: 'greetById'

**After:** Use the :php:`#[AsHelper]` attribute directly on the class or method:

..  code-block:: php
    :caption: EXT:my_extension/Classes/Renderer/Helper/GreetHelper.php

    use CPSIT\Typo3Handlebars\Attribute\AsHelper;
    use CPSIT\Typo3Handlebars\Renderer\Helper\Helper;
    use DevTheorem\Handlebars\HelperOptions;

    #[AsHelper('greet')]
    final readonly class GreetHelper implements Helper
    {
        public function render(HelperOptions $options): string { /* ... */ }
    }

The :file:`Services.yaml` tag approach still works and can be used if you
cannot modify the helper class (e.g., a third-party class).

..  _migration-1-debug-mode:

Debug mode
----------

The debug mode built into :php:`HandlebarsRenderer` has been removed. Previously,
when TYPO3's :typoscript:`config.debug` flag or
:php:`$GLOBALS['TYPO3_CONF_VARS']['FE']['debug']` was enabled, the renderer
automatically bypassed the template cache and switched the Handlebars compiler
to strict mode (throwing on missing variables instead of silently returning
empty strings).

There is no automatic replacement tied to a debug flag. Use the following
alternatives instead:

*   **Cache bypass:** Disable caching explicitly via
    :ref:`TYPO3's caching framework <t3coreapi:caching>` configuration or by
    setting :typoscript:`config.no_cache = 1` during development.
*   **Strict compilation:** Enable
    :ref:`rendering.strictMode <extension-configuration-rendering-strict-mode>`
    in the extension configuration. Unlike the previous behavior, this is a
    persistent setting rather than one tied to TYPO3's debug flags.
*   **Strict template validation:** Use the shipped :ref:`{{debug}} <templates-helpers-debug>`
    helper inside templates to inspect variable values at render time. For
    programmatic checks, call :php:`Handlebars::precompile()` directly to
    inspect the generated PHP code.

..  _migration-1-template-paths:

Template path configuration
----------------------------

No migration needed. Template path configuration via :file:`Services.yaml`
and TypoScript remains unchanged; paths can now additionally be set per
content object (see :ref:`template-paths`).