Creating a new task

Creating the task class

This is the heart of a task. It is the code that actually does what the task is supposed to do. A task is represented by a PHP class that extends the base task class:

namespace Vendor\Extension\Task;
class MyTask extends \TYPO3\CMS\Scheduler\Task\AbstractTask {
        public function execute() {
                ...
        }
}

The only method that must be implemented is the execute() method which is expected to perform the task logic. The method must return a boolean value of "true" if the execution was successful, and "false" otherwise. It may also throw exceptions to report more precisely on errors that may happen during the run. The message of the exception is stored in the database so that it can be displayed in the BE module.

A method called getAdditionalInformation() may optionally be implemented too. It is called by the BE module to display additional information about a registered task in the list view. This is quite convenient if a task class may be registered several times with different parameters, in order to tell apart the various registrations.

If the task class uses a constructor it is absolutely necessary to include a call to the parent's constructor, most probably as the first thing inside the constructor, unless there are some very special reasons not to:

namespace Vendor\Extension\Task;
class MyTask extends \TYPO3\CMS\Scheduler\Task\AbstractTask {
        public function __construct() {
                parent::__construct();
                // Your code here...
        }
}

Using additional fields

A task class may require additional parameters to be executed properly. For example, the "test" task is designed to send an e-mail, but the e-mail address must be defined at the time when the task class is actually registered. This appears as an additional field in the task registration form. The Scheduler provides an interface which may be implemented to provide such fields. It is comprised of three methods, which must all be implemented (since it's an interface).

The implementation may be done in a separate class or in the same class as the task. It may look something like:

namespace Vendor\Extension\Task;
class MyTaskAdditionalFieldProvider implements \TYPO3\CMS\Scheduler\AdditionalFieldProviderInterface {
        public function getAdditionalFields(array &$taskInfo, $task, \TYPO3\CMS\Scheduler\Controller\SchedulerModuleController $parentObject) {
                ...
        }
        public function validateAdditionalFields(array &$submittedData, \TYPO3\CMS\Scheduler\Controller\SchedulerModuleController $parentObject) {
                ...
        }
        public function saveAdditionalFields(array $submittedData, \TYPO3\CMS\Scheduler\Task\AbstractTask $task) {
                ...
        }
}

The three methods of the interface are described below:

getAdditionalFields

Method

getAdditionalFields

Purpose

This method returns the list of fields to display in the editing form.

This list of fields is a 2-dimensional array. The first dimension uses the ID of the field (as used in the "id" attribute of the field tag). Then for each field, there must be the HTML code to render the field, the label of the field, the key and the label for the context- sensitive help (CSH).

All this is documented in the \TYPO3\CMS\Scheduler\AdditionalFieldProviderInterface interface and can be seen in action in the existing task classes.

Parameters

$taskInfo : an array containing the information about the current task. May be modified inside this method to set default values, for example.

$task : the current task object (when editing; when adding, "null" is passed to the method).

$parentObject : a back-reference to the calling BE module's object.

validateAdditionalFields

Method

validateAdditionalFields

Purpose

This method is called to validate the values that were input in the additional fields provided by the specific task. It is expected to return false if any of the fields contained errors, true otherwise.

The method should use the parent object's addMessage() method to output messages about validation errors.

Parameters

$submittedData : array of values from the submitted form. May be modified inside the method.

$parentObject : a back-reference to the calling BE module's object.

saveAdditionalFields

Method

saveAdditionalFields

Purpose

This method is used to store the values contained in the additional fields. The simplest method is to simply assign them to member variables, so that they will be stored along the serialized task object in the database (see Appendix A – Technical Background).

Parameters

$submittedData : array of values from the submitted form, after validation.

$task : the current task object.

Security issues

The handling of additional fields is entirely up to the developer, in particular as far as validation and display is concerned. Thus it is up to you to make sure that the data entered in your additional fields does not contain any harmful input (for example, XSS).

The safest way to proceed is to very strictly handle input. For example, if all you expect is some integer number, pass the value through a typecast to (int). If it's a string, but you don't expect any markup in it, run it through strip\_tags() . Such simple measures can filter most of the harmful code.

One more thing to mind. In the getAdditionalFields() method, the whole form element must be assembled. If the input didn't validate, you may well want to insert it in the field again, so that the user can correct it. Harmful code entered at that point may be executed. It is thus very strongly recommended to use htmlspecialchars() in this case. Example:

$fieldCode = '<input type="text" class="form-control" name="tx_scheduler[email]" id="' . $fieldID . '" value="' . htmlspecialchars($taskInfo['email']) . '" size="30">';

Naming of additional fields

The Scheduler expects all fields in the add/edit form to be named tx\_scheduler[...] . Values from fields that don't follow this pattern will not appear in the $submittedData array.

It is also important to think about using field names that will not create conflicts with other existing fields or future fields that may happen. Since there is no name-spacing mechanism available, it is up to each developer to choose proper names. A very good practice is to prepend the extension's key to the additional fields names in order to guarantee the unicity of those names.

Bad examples

Here are some examples of bad additional fields names:

foo
tx_scheduler[name]

The first name doesn't use the syntax and thus will not be handled by the Scheduler. The second one respects that syntax, but the name is too generic and may cause conflicts with other fields.

Good examples

Here are good examples of additional fields names:

tx_scheduler[myextension_myvalue]
tx_scheduler[myextension][myvalue]

In both cases the proper syntax is used as well as the extension key, making it very unlikely that a naming conflict could happen.

Declaring the task class

As a last step, the task class must be declared so the Scheduler knows of its existence. The declaration must be placed in the ext_localconf.php file of the extension that provides the task. Let's look at one of the base classes declaration as an example:

// Add caching framework garbage collection task
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['scheduler']['tasks'][\TYPO3\CMS\Scheduler\Task\CachingFrameworkGarbageCollectionTask::class] = array(
        'extension' => 'your_extension_key,
        'title' => 'LLL:EXT:your_extension_key/locallang.xlf:cachingFrameworkGarbageCollection.name',
        'description' => 'LLL:EXT:your_extension_key/locallang.xlf:cachingFrameworkGarbageCollection.description',
        'additionalFields' => \TYPO3\CMS\Scheduler\Task\CachingFrameworkGarbageCollectionAdditionalFieldProvider::class
);

The registration is made in the array $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['scheduler']['tasks']. The key used corresponds to the task class. Then come 4 parameters:

  • extension : the key of the extension that provides the class. This is used for informational purposes.
  • title : the name of the task. May use localized labels.
  • description : a text describing the task. It is displayed in the information screen of the BE module. May use localized labels.
  • additionalFields : the name of the class that provides the additional fields. Leave empty if task class does not require any such fields.

Working with serialized objects

When a task is registered with the Scheduler the corresponding object instance is serialized and stored in the database (see Appendix A for more details). This is not a very common practice. There are advantages but also some pitfalls, so please read this section carefully.

A serialized object may happen to be "out of sync" with its class if the class changes some of its variables or methods. If a variable's name is changed or if variables are added or removed, the serialized object will not reflect these changes. The same goes if a method is renamed, added or deleted. Problems will also arise if the number or order of arguments used to call a method are changed. In such cases weird errors may appear, which can be very difficult to track. The only solution is to delete the registered task and register it anew.

To minimize such risks it is worth to consider implementing the business logic in a separate class, so that the task class itself changes as little as possible. The execute() should be as simple as possible. Consider the following:

class MyTask extends \TYPO3\CMS\Scheduler\Task\AbstractTask {
        public function execute() {
                $businessLogic = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\Vendor\Extension\BusinessLogic::class);
                $businessLogic->run(arg1, arg2, );
        }
}

In such a setup the execute() is kept to the strict minimum and the operations themselves are handled by a separate class.

Also remember that the constructor is not called when unserializing an object. If some operations need to be run upon unserialization, implement a __wakeup() method instead.

Saving a task's state

The task's state is saved automatically at the start of its execution. If you need to save a task's state at some point during its execution, you can simply call the task's own save() method.