111 lines
4.5 KiB
ReStructuredText
111 lines
4.5 KiB
ReStructuredText
:navigation-title: Migration
|
|
|
|
.. include:: /Includes.rst.txt
|
|
|
|
.. _task-migration:
|
|
|
|
=====================================================
|
|
Migration to the TCA registration for scheduler tasks
|
|
=====================================================
|
|
|
|
.. deprecated:: 14.0
|
|
Registering tasks and additional field providers via
|
|
:php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['scheduler']['tasks']` has
|
|
been deprecated.
|
|
|
|
The :php-short:`\TYPO3\CMS\Scheduler\AdditionalFieldProviderInterface` and
|
|
:php-short:`\TYPO3\CMS\Scheduler\AbstractAdditionalFieldProvider` have also
|
|
been deprecated.
|
|
|
|
.. contents:: Table of contents
|
|
|
|
Tasks in general and additional fields for tasks are registered via TCA
|
|
instead.
|
|
.. _additional-fields-migration:
|
|
|
|
Migrating tasks with AdditionalFieldProviders to TCA registration
|
|
=================================================================
|
|
|
|
Scheduler tasks should now be registered as native task types using TCA.
|
|
This provides a more integrated and maintainable approach to task configuration.
|
|
|
|
.. _additional-fields-migration-steps:
|
|
|
|
Migration steps:
|
|
----------------
|
|
|
|
1. Remove the registration from :file:`ext_localconf.php`
|
|
2. Create a TCA override file in :file:`Configuration/TCA/Overrides/scheduler_my_task_type.php`
|
|
3. Update your task class to implement the new parameter methods
|
|
4. Remove the :php:`AdditionalFieldProvider` class if it exists
|
|
|
|
.. note::
|
|
The new TCA-based approach automatically migrates existing task data.
|
|
When upgrading, existing task configurations are preserved through the
|
|
:php:`getTaskParameters()` and :php:`setTaskParameters()` methods.
|
|
|
|
.. _additional-fields-migration-example:
|
|
|
|
Example migration: Scheduler task with additional fields suppporting TYPO3 13 and 14
|
|
------------------------------------------------------------------------------------
|
|
|
|
Remove the registration from :file:`ext_localconf.php` once TYPO3 13 support is
|
|
dropped:
|
|
|
|
.. literalinclude:: _codesnippets/_ext_localconf_deprecated.php.inc
|
|
:language: php
|
|
:caption: packages/my_extension/ext_localconf.php
|
|
|
|
And also remove the :php:`MyTaskAdditionalFieldProvider` class once
|
|
TYPO3 13 support is dropped.
|
|
|
|
Create a TCA override file in :file:`Configuration/TCA/Overrides/scheduler_my_task_type.php`:
|
|
|
|
.. literalinclude:: _codesnippets/_scheduler_my_task_type-additional.php.inc
|
|
:language: php
|
|
:caption: EXT:my_extension/Configuration/TCA/Overrides/scheduler_my_task_type.php
|
|
|
|
Update your (existing) task class to implement the new methods:
|
|
|
|
.. literalinclude:: _codesnippets/_MyTaskWithAdditionalFieldsMigration.php.inc
|
|
:language: php
|
|
:caption: packages/my_extension/Classes/MyTask.php
|
|
|
|
The new TCA-based approach uses three key methods for parameter handling:
|
|
|
|
**getTaskParameters(): array**
|
|
This method is already implemented in ``AbstractTask`` to handle task class
|
|
properties automatically, but can be overridden in task classes for custom
|
|
behavior.
|
|
|
|
The method is primarily used:
|
|
|
|
* For migration from old serialized task format to new TCA structure
|
|
* For non-native (deprecated) task types to store their values in the legacy ``parameters`` field
|
|
|
|
For native TCA tasks, this method is typically no longer needed in custom
|
|
tasks after the migration has been done, since field values are then stored
|
|
directly in database columns.
|
|
|
|
**setTaskParameters(array $parameters): void**
|
|
Sets field values from an associative array. This method handles:
|
|
|
|
* Migration from old AdditionalFieldProvider field names to new TCA field names
|
|
* Loading saved task configurations when editing or executing tasks
|
|
* Parameter mapping during task creation and updates
|
|
* The method should always be implemented, especially for native tasks
|
|
|
|
The migration pattern is: :php:`$this->myField = $parameters['oldName'] ?? $parameters['new_tca_field_name'] ?? '';`
|
|
|
|
**validateTaskParameters(array $parameters): bool**
|
|
*Optional method.* Only implement this for validation that cannot be handled by FormEngine.
|
|
|
|
* Basic validation (required, trim, etc.) should be done via TCA configuration (``required`` property and ``eval`` options)
|
|
* Use this method for complex business logic validation (e.g., email format validation, external API checks)
|
|
* Return ``false`` and add FlashMessage for validation errors
|
|
* FormEngine automatically handles standard TCA validation rules
|
|
|
|
For a complete working example, see :php:`\TYPO3\CMS\Reports\Task\SystemStatusUpdateTask`
|
|
and its corresponding TCA configuration in
|
|
:file:`EXT:reports/Configuration/TCA/Overrides/scheduler_system_status_update_task.php`.
|