Cron Tasks

Schedule automated tasks to run periodically.

Cron Task Interface

<?php
namespace Plugins\MyPlugin\CronTask;

use App\Core\Cron\PluginCronTaskInterface;
use Psr\Log\LoggerInterface;

class MyCleanupTask implements PluginCronTaskInterface
{
    public function __construct(
        private readonly MyService $myService,
        private readonly LoggerInterface $logger,
    ) {}

    public function execute(): void
    {
        $this->logger->info('Running cleanup task');

        try {
            $deletedCount = $this->myService->cleanupOldData();

            $this->logger->info('Cleanup completed', [
                'deleted_count' => $deletedCount
            ]);
        } catch (\Exception $e) {
            $this->logger->error('Cleanup failed', [
                'error' => $e->getMessage()
            ]);

            throw $e;
        }
    }

    public function getSchedule(): string
    {
        // Cron expression
        return '0 3 * * *';  // Daily at 3 AM
    }

    public function getName(): string
    {
        return 'my-plugin:cleanup';
    }

    public function getDescription(): string
    {
        return 'Clean up old data from my-plugin tables';
    }

    public function isEnabled(): bool
    {
        // Control whether task should run
        return true;
    }
}

Cron Expression Syntax

Expression	Meaning	When it runs
* * * * *	Every minute	Every minute
*/5 * * * *	Every 5 minutes	:00, :05, :10, ...
0 * * * *	Every hour	Top of every hour
0 */6 * * *	Every 6 hours	00:00, 06:00, 12:00, 18:00
0 3 * * *	Daily at 3 AM	Once per day
0 0 * * 0	Weekly on Sunday	Sunday at midnight
0 0 1 * *	Monthly on 1st	First day of month

Cron Expression Format

*    *    *    *    *
┬    ┬    ┬    ┬    ┬
│    │    │    │    │
│    │    │    │    └─── Day of Week   (0-6) (Sunday=0)
│    │    │    └──────── Month          (1-12)
│    │    └───────────── Day of Month   (1-31)
│    └────────────────── Hour           (0-23)
└─────────────────────── Minute         (0-59)

Advanced Cron Task

class AdvancedTask implements PluginCronTaskInterface
{
    public function execute(): void
    {
        $startTime = microtime(true);

        // Task logic
        $this->myService->performTask();

        $duration = microtime(true) - $startTime;

        $this->logger->info('Task completed', [
            'duration' => $duration,
            'memory' => memory_get_peak_usage(true)
        ]);
    }

    public function isEnabled(): bool
    {
        // Only run if plugin setting is enabled
        $enabled = $this->pluginSettings->get('my-plugin', 'cron_enabled', false);
        return (bool) $enabled;
    }
}

Service Registration

services:
    Plugins\MyPlugin\CronTask\MyCleanupTask:
        tags: ['plugin.cron_task']

Important: Cron tasks must be tagged with plugin.cron_task.

Task Examples

Daily Database Cleanup

class DatabaseCleanupTask implements PluginCronTaskInterface
{
    public function execute(): void
    {
        // Delete logs older than 30 days
        $cutoffDate = new \DateTimeImmutable('-30 days');

        $deleted = $this->repository
            ->createQueryBuilder('l')
            ->delete()
            ->where('l.createdAt < :cutoff')
            ->setParameter('cutoff', $cutoffDate)
            ->getQuery()
            ->execute();

        $this->logger->info('Cleaned up old logs', ['deleted' => $deleted]);
    }

    public function getSchedule(): string
    {
        return '0 2 * * *';  // Daily at 2 AM
    }
}

Hourly Data Sync

class DataSyncTask implements PluginCronTaskInterface
{
    public function execute(): void
    {
        // Sync data with external API
        $data = $this->externalApi->fetchLatestData();

        foreach ($data as $item) {
            $this->processDataItem($item);
        }

        $this->logger->info('Data sync completed', ['items' => count($data)]);
    }

    public function getSchedule(): string
    {
        return '0 * * * *';  // Every hour
    }
}

Weekly Report Generation

class WeeklyReportTask implements PluginCronTaskInterface
{
    public function execute(): void
    {
        // Generate weekly statistics
        $stats = $this->statsService->generateWeeklyReport();

        // Send email to admins
        $this->mailer->sendWeeklyReport($stats);

        $this->logger->info('Weekly report sent');
    }

    public function getSchedule(): string
    {
        return '0 9 * * 1';  // Every Monday at 9 AM
    }
}

Server Health Monitoring

Monitor server health and send alerts when issues detected.

class ServerHealthCheckTask implements PluginCronTaskInterface
{
    public function execute(): void
    {
        $servers = $this->serverRepository->findAllActive();
        $unhealthyServers = [];

        foreach ($servers as $server) {
            $health = $this->pterodactylService->checkServerHealth($server);

            if (!$health->isHealthy()) {
                $unhealthyServers[] = [
                    'server' => $server,
                    'issues' => $health->getIssues(),
                    'status' => $health->getStatus(),
                ];

                // Log issue
                $this->logger->warning('Unhealthy server detected', [
                    'server_id' => $server->getId(),
                    'server_name' => $server->getName(),
                    'issues' => implode(', ', $health->getIssues()),
                ]);
            }
        }

        // Notify admins if issues found
        if (!empty($unhealthyServers)) {
            $this->notificationService->notifyAdmins(
                'Server Health Alert',
                $this->renderHealthReport($unhealthyServers)
            );
        }

        $this->logger->info('Health check completed', [
            'total_servers' => count($servers),
            'unhealthy_count' => count($unhealthyServers),
        ]);
    }

    public function getSchedule(): string
    {
        return '*/15 * * * *';  // Every 15 minutes
    }

    public function getName(): string
    {
        return 'server-monitor:health-check';
    }

    public function getDescription(): string
    {
        return 'Monitor server health and alert on issues';
    }

    public function isEnabled(): bool
    {
        return $this->pluginSettings->get('server-monitor', 'health_check_enabled', true);
    }

    private function renderHealthReport(array $unhealthyServers): string
    {
        $report = "Server Health Report\n\n";
        $report .= sprintf("Found %d unhealthy servers:\n\n", count($unhealthyServers));

        foreach ($unhealthyServers as $data) {
            $server = $data['server'];
            $report .= sprintf(
                "- %s (ID: %d)\n  Status: %s\n  Issues: %s\n\n",
                $server->getName(),
                $server->getId(),
                $data['status'],
                implode(', ', $data['issues'])
            );
        }

        return $report;
    }
}

Expiration Reminder Notifications

Send reminders to users about expiring servers.

class ExpirationReminderTask implements PluginCronTaskInterface
{
    public function execute(): void
    {
        // Find servers expiring in next 3 days
        $expiringServers = $this->serverRepository->findExpiringSoon(days: 3);

        foreach ($expiringServers as $server) {
            $daysRemaining = $this->calculateDaysRemaining($server);

            // Send email notification
            $this->emailService->send(
                to: $server->getUser()->getEmail(),
                template: 'server_expiring_soon',
                data: [
                    'server' => $server,
                    'days_remaining' => $daysRemaining,
                    'renewal_url' => $this->generateRenewalUrl($server),
                ]
            );

            // Create in-panel notification
            $this->notificationService->createNotification(
                user: $server->getUser(),
                type: 'warning',
                title: 'Server Expiring Soon',
                message: sprintf(
                    'Your server "%s" will expire in %d days. Renew now to avoid interruption.',
                    $server->getName(),
                    $daysRemaining
                ),
                actionUrl: $this->generateRenewalUrl($server),
                actionText: 'Renew Now'
            );

            $this->logger->info('Expiration reminder sent', [
                'server_id' => $server->getId(),
                'user_id' => $server->getUser()->getId(),
                'days_remaining' => $daysRemaining,
            ]);
        }

        $this->logger->info('Expiration reminders completed', [
            'reminders_sent' => count($expiringServers),
        ]);
    }

    public function getSchedule(): string
    {
        return '0 10 * * *';  // Daily at 10 AM
    }

    public function getName(): string
    {
        return 'notification:expiration-reminders';
    }

    public function getDescription(): string
    {
        return 'Send reminders for expiring servers';
    }

    public function isEnabled(): bool
    {
        return $this->pluginSettings->get('notifications', 'expiration_reminders_enabled', true);
    }

    private function calculateDaysRemaining(Server $server): int
    {
        $now = new \DateTimeImmutable();
        $expiry = $server->getExpiresAt();
        $diff = $now->diff($expiry);
        return $diff->days;
    }

    private function generateRenewalUrl(Server $server): string
    {
        return sprintf(
            '%s/server/renew?id=%s',
            $this->systemSettings->get('site_url'),
            $server->getIdentifier()
        );
    }
}

Automatic Backup Cleanup

Clean up old server backups to free storage space.

class BackupCleanupTask implements PluginCronTaskInterface
{
    public function execute(): void
    {
        $retentionDays = $this->pluginSettings->get('backup-manager', 'retention_days', 30);
        $cutoffDate = new \DateTimeImmutable("-{$retentionDays} days");

        $servers = $this->serverRepository->findAll();
        $totalDeleted = 0;

        foreach ($servers as $server) {
            try {
                $backups = $this->pterodactylService->getServerBackups($server);
                $oldBackups = array_filter(
                    $backups,
                    fn($backup) => $backup->getCreatedAt() < $cutoffDate
                );

                foreach ($oldBackups as $backup) {
                    $this->pterodactylService->deleteBackup($server, $backup);
                    $totalDeleted++;

                    $this->logger->debug('Backup deleted', [
                        'server_id' => $server->getId(),
                        'backup_id' => $backup->getId(),
                        'age_days' => $cutoffDate->diff($backup->getCreatedAt())->days,
                    ]);
                }

                if (count($oldBackups) > 0) {
                    $this->logger->info('Cleaned up old backups', [
                        'server_id' => $server->getId(),
                        'deleted_count' => count($oldBackups),
                    ]);
                }
            } catch (\Exception $e) {
                $this->logger->error('Backup cleanup failed for server', [
                    'server_id' => $server->getId(),
                    'error' => $e->getMessage(),
                ]);
                // Continue with next server
            }
        }

        $this->logger->info('Backup cleanup completed', [
            'total_deleted' => $totalDeleted,
            'retention_days' => $retentionDays,
        ]);
    }

    public function getSchedule(): string
    {
        return '0 4 * * 0';  // Weekly on Sunday at 4 AM
    }

    public function getName(): string
    {
        return 'backup:cleanup-old';
    }

    public function getDescription(): string
    {
        return 'Remove backups older than retention period';
    }

    public function isEnabled(): bool
    {
        return $this->pluginSettings->get('backup-manager', 'auto_cleanup_enabled', false);
    }
}

Analytics Data Aggregation

Aggregate and process analytics data for reporting.

class AnalyticsAggregationTask implements PluginCronTaskInterface
{
    public function execute(): void
    {
        $yesterday = new \DateTimeImmutable('yesterday');

        // Aggregate revenue data
        $revenue = $this->calculateDailyRevenue($yesterday);

        // Aggregate server statistics
        $serverStats = $this->aggregateServerStats($yesterday);

        // Aggregate user activity
        $userStats = $this->aggregateUserActivity($yesterday);

        // Store aggregated data
        $report = new DailyAnalyticsReport();
        $report->setDate($yesterday);
        $report->setRevenue($revenue);
        $report->setServerStats($serverStats);
        $report->setUserStats($userStats);

        $this->entityManager->persist($report);
        $this->entityManager->flush();

        $this->logger->info('Daily analytics aggregated', [
            'date' => $yesterday->format('Y-m-d'),
            'revenue' => $revenue,
            'servers_created' => $serverStats['created'],
            'active_users' => $userStats['active'],
        ]);

        // Generate and cache charts
        $this->generateAnalyticsCharts($report);
    }

    public function getSchedule(): string
    {
        return '0 5 * * *';  // Daily at 5 AM
    }

    public function getName(): string
    {
        return 'analytics:aggregate-daily';
    }

    public function getDescription(): string
    {
        return 'Aggregate daily analytics data for reporting';
    }

    public function isEnabled(): bool
    {
        return true;
    }

    private function calculateDailyRevenue(\DateTimeImmutable $date): float
    {
        return $this->paymentRepository
            ->createQueryBuilder('p')
            ->select('SUM(p.amount)')
            ->where('p.status = :status')
            ->andWhere('p.createdAt >= :start')
            ->andWhere('p.createdAt < :end')
            ->setParameter('status', 'completed')
            ->setParameter('start', $date->setTime(0, 0))
            ->setParameter('end', $date->modify('+1 day')->setTime(0, 0))
            ->getQuery()
            ->getSingleScalarResult() ?? 0.0;
    }

    private function aggregateServerStats(\DateTimeImmutable $date): array
    {
        // Count servers created
        $created = $this->serverRepository->countCreatedOnDate($date);

        // Count servers deleted
        $deleted = $this->serverRepository->countDeletedOnDate($date);

        // Count active servers
        $active = $this->serverRepository->countActiveOnDate($date);

        return [
            'created' => $created,
            'deleted' => $deleted,
            'active' => $active,
            'net_change' => $created - $deleted,
        ];
    }

    private function aggregateUserActivity(\DateTimeImmutable $date): array
    {
        // Count active users (logged in during day)
        $active = $this->userRepository->countActiveOnDate($date);

        // Count new registrations
        $registered = $this->userRepository->countRegisteredOnDate($date);

        return [
            'active' => $active,
            'registered' => $registered,
        ];
    }

    private function generateAnalyticsCharts(DailyAnalyticsReport $report): void
    {
        // Generate chart images/data for dashboard
        $this->chartService->generateRevenueChart($report);
        $this->chartService->generateServerGrowthChart($report);
        $this->chartService->generateUserActivityChart($report);
    }
}

Error Handling

public function execute(): void
{
    try {
        $this->performTask();
    } catch (\Exception $e) {
        $this->logger->error('Cron task failed', [
            'task' => $this->getName(),
            'error' => $e->getMessage(),
            'trace' => $e->getTraceAsString()
        ]);

        // Optionally notify admins
        $this->notifyAdmins($e);

        // Re-throw to mark task as failed
        throw $e;
    }
}

Conditional Execution

public function isEnabled(): bool
{
    // Check plugin setting
    $enabled = $this->pluginSettings->get('my-plugin', 'sync_enabled');
    if (!$enabled) {
        return false;
    }

    // Check system status
    if ($this->systemStatus->isMaintenanceMode()) {
        return false;
    }

    // Check time-based conditions
    $hour = (int) date('H');
    if ($hour >= 9 && $hour <= 17) {
        // Don't run during business hours
        return false;
    }

    return true;
}

Best Practices

1. Keep tasks fast - they block other tasks

2. Handle errors gracefully - don't let exceptions break cron

3. Log execution - track when tasks run and their results

4. Use appropriate schedules - don't run tasks more often than needed

5. Make tasks idempotent - safe to run multiple times

6. Check isEnabled() - allow users to disable tasks

7. Monitor performance - track execution time and memory

8. Batch operations - process data in chunks to avoid memory issues

Monitoring Cron Tasks

Check task execution:

php bin/console pteroca:cron:list
php bin/console pteroca:cron:run my-plugin:cleanup --dry-run

Related Guides

• Console Commands - Manual task execution

• Dependencies - Service injection

• Best Practices - Performance optimization