Nightly Task Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dekalee/nightly-task-bundle
   

   For Symfony <4.x, register the bundle in AppKernel.php:

   new Dekalee\NightlyTaskBundle\DekaleeNightlyTaskBundle(),
   

2. First Use Case Tag an existing console command as a nightly task by adding the dekalee.nightly_task tag in its definition (e.g., src/Command/MyNightlyCommand.php):

   # config/services.yaml
   services:
       App\Command\MyNightlyCommand:
           tags: ['console.command', 'dekalee.nightly_task']
   

3. Verify Registration List registered nightly tasks:

   ./bin/console dekalee:nightly:list
   

Implementation Patterns

Workflow Integration

1. Tagging Commands Use the dekalee.nightly_task tag to include any Symfony console command in the nightly execution pipeline. Example:

   # config/services.yaml
   services:
       App\Command\BackupDatabaseCommand:
           tags: ['console.command', 'dekalee.nightly_task']
       App\Command\CleanupLogsCommand:
           tags: ['console.command', 'dekalee.nightly_task']
   

2. Ordering Tasks Define execution order via the dekalee.nightly_task.order argument (default: 0):

   services:
       App\Command\HighPriorityTask:
           tags: ['console.command', 'dekalee.nightly_task']
           arguments:
               $order: 10  # Runs before tasks with lower order
   

3. Conditional Execution Skip tasks based on environment variables or logic:

   // In your command class
   protected function execute(InputInterface $input, OutputInterface $output): int
   {
       if (!$this->getContainer()->getParameter('run_nightly_tasks')) {
           $output->writeln('Skipped: Nightly tasks disabled.');
           return Command::SUCCESS;
       }
       // ... rest of the logic
   }
   

4. Scheduling with Cron Add a cron job to trigger nightly tasks (e.g., via crontab or a hosting provider):

   0 3 * * * cd /path/to/project && php bin/console dekalee:nightly:tasks >> /var/log/nightly_tasks.log 2>&1
   

5. Logging and Monitoring Redirect output to a log file for debugging:

   ./bin/console dekalee:nightly:tasks --no-debug >> storage/logs/nightly_tasks.log 2>&1
   

Gotchas and Tips

Pitfalls

1. Command Dependencies

   • If a nightly task fails, subsequent tasks may still run unless explicitly handled. Use return Command::FAILURE to halt execution.
   • Example:

     if ($this->checkCriticalCondition()) {
         $this->output->writeln('Critical failure!');
         return Command::FAILURE;
     }
     

2. Order Collisions

   • Tasks with the same order value may execute in an undefined sequence. Avoid ambiguity by using distinct values.

3. Environment-Specific Tasks

   • Ensure tasks are only registered for the correct environment (e.g., dev vs. prod). Use Symfony’s environment-aware services:

     # config/services.yaml
     App\Command\DevOnlyTask:
         tags: ['console.command', 'dekalee.nightly_task']
         calls:
             - [setEnvironment, ['%kernel.environment%']]
     

4. Performance Overhead

   • Avoid long-running tasks in the nightly bundle. Offload heavy operations to queue workers (e.g., Laravel Queues or Symfony Messenger).

5. Testing Nightly Tasks

   • Mock the dekalee:nightly:tasks command in PHPUnit tests:

     $this->executeCommand('dekalee:nightly:tasks', [
         '--env' => 'test',
     ]);
     

Debugging Tips

1. Dry Run Mode Simulate execution without running commands:

   ./bin/console dekalee:nightly:list --verbose
   

2. Logging Enable debug mode for verbose output:

   ./bin/console dekalee:nightly:tasks --no-interaction --debug
   

3. Isolation Test individual tasks separately before bundling them:

   ./bin/console app:backup-database --no-interaction
   

Extension Points

1. Custom Task Groups Extend the bundle to support dynamic task grouping (e.g., by priority or category). Override the NightlyTaskManager service:

   # config/services.yaml
   Dekalee\NightlyTaskBundle\Manager\NightlyTaskManager:
       class: App\Service\CustomNightlyTaskManager
   

2. Pre/Post-Hooks Add lifecycle hooks (e.g., send notifications before/after execution) by subscribing to the dekalee.nightly_task.run event:

   // src/EventListener/NightlyTaskListener.php
   public static function getSubscribedEvents(): array
   {
       return [
           'dekalee.nightly_task.run' => 'onNightlyTaskRun',
       ];
   }
   

3. Dynamic Task Registration Register tasks programmatically (e.g., from a database) by implementing a custom TaskLoader:

   // src/Service/DynamicTaskLoader.php
   class DynamicTaskLoader implements TaskLoaderInterface
   {
       public function load(): array
       {
           return $this->fetchTasksFromDatabase();
       }
   }
   

   Then override the service:

   Dekalee\NightlyTaskBundle\Loader\TaskLoader:
       class: App\Service\DynamicTaskLoader