Architecting Reliable Background Tasks with the TYPO3 Scheduler

The Problem: Avoiding Task Overlap and Silent Failures

Implementing background tasks in TYPO3 often leads to two critical failures: tasks that never run because the system cron is misconfigured, or tasks that crash the PHP process, preventing subsequent scheduled jobs from executing. The goal is to move from a "set and forget" mentality to a design that ensures execution visibility and prevents resource exhaustion.

Requirements for a Functional Scheduler

The TYPO3 Scheduler is not a daemon; it is a trigger-based system. To function, it requires two components:

• The Trigger: A system-level cron job that invokes the TYPO3 CLI.
• The Definition: A database-backed task configuration that defines the frequency and the PHP class to be executed.

The Minimal Design: Implementing a Custom Task

The smallest suitable design for a background task involves extending the AbstractTask class. This ensures the task integrates with the TYPO3 Backend UI for manual triggering and monitoring.

Implementation Example:

namespace Vendor\Extension\Scheduler\Task;

use TYPO3\CMS\Scheduler\Task

class MyCustomTask extends AbstractTask {
    public function execute(): void {
        // Business logic goes here
        // Example: Cleaning up expired temporary files
    }
}

After defining the class, the task must be registered in the extension configuration (typically via ext_localconf.php or the Backend module) to be visible to the scheduler runner.

Trust and Data Boundaries

Tasks execute under the permissions of the user running the CLI command. This creates a potential boundary conflict between the CLI User and the Web Server User (e.g., www-data).

Boundary	Constraint	Risk
Filesystem	CLI user must have write access to var/ and public/upload/.	Permission denied errors when clearing cache or writing logs.
Database	Uses the configured TYPO3 database user.	Limited by the DB user's grants (usually sufficient for standard tasks).
Execution	Runs as a sequential PHP process.	A single hanging task blocks all subsequent tasks in the queue.

Operational Checks and Verification

To verify the scheduler is operational, do not rely solely on the Backend UI. Perform a manual CLI trigger to isolate the PHP environment from the cron environment.

Manual Execution:
Run this command from the TYPO3 root directory as the web server user:

sudo -u www-data php bin/typo3 scheduler:run

Verification Steps:

1. Check the terminal output for any PHP Fatal errors.
2. Navigate to the TYPO3 Backend > System > Scheduler.
3. Verify the "Last Run" timestamp for your task has updated to the current time.
4. If the task writes to a log, verify the file ownership is correct (should be the web server user).

Failure Modes and Mitigation

Silent Failure: If the system cron is missing or the PHP binary path is incorrect in the crontab, the scheduler will simply not run. Monitor the system mail or cron logs (e.g., /var/log/syslog) for execution errors.

Overlapping Executions: If a task is scheduled every minute but takes two minutes to complete, multiple instances of the same task may run simultaneously. This can lead to database deadlocks or race conditions. To mitigate this, implement a custom locking mechanism using the TYPO3 Cache framework or a filesystem lock.

When to Change the Design

The built-in Scheduler is designed for low-to-medium volume administrative tasks. You should migrate to a distributed queue system (such as RabbitMQ or Redis with a dedicated worker) if the following conditions are met:

• Volume: The number of tasks per hour exceeds the capacity of a single sequential PHP process.
• Latency: Tasks require immediate execution upon a specific event rather than waiting for the next cron tick.
• Isolation: A failure in one task must not impact the execution of others.

Rollback: If a custom task causes system instability, disable the task via the TYPO3 Backend Scheduler module. This prevents the scheduler:run command from invoking the problematic class without requiring a code deployment.