Cron Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require draw/cron-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Draw\CronBundle\DrawCronBundle::class => ['all' => true],
   ];
   

2. Configure: Add the bundle configuration to config/packages/draw_cron.yaml (or merge into config/packages/dev/your_app.yaml):

   draw_cron:
       jobs:
           my_first_job:
               description: "My first cron job"
               command: "php bin/console my:command"
               expression: "* * * * *"
               enabled: true
   

3. First Use Case: Run the dump command to generate a cron file:

   bin/console draw:cron:dump-to-file /etc/cron.d/myapp
   

   This creates a file with the configured cron jobs in the standard cron format.

Implementation Patterns

Centralized Configuration

• Environment-Specific Jobs: Use parameters (e.g., %cron.context.enabled%) to toggle jobs per environment (e.g., dev, prod).

  draw_cron:
      jobs:
          analytics_job:
              enabled: "%kernel.debug%"  # Disabled in production
  

• Dynamic Command Paths: Reference the console.execution parameter for cross-environment compatibility:

  command: "%cron.console.execution% my:command --env=%kernel.environment%"
  

Workflows

1. Development:

   • Test cron jobs locally by dumping to a file (e.g., cron.dev) and manually adding it to your system’s crontab.
   • Use enabled: false for jobs that shouldn’t run locally.

2. Deployment:

   • Integrate draw:cron:dump-to-file into your deployment script (e.g., Ansible, Deployer) to update /etc/cron.d/your_app atomically.
   • Example (Deployer):

     task('deploy:cron', function () {
         run('cd {{release_path}} && bin/console draw:cron:dump-to-file /etc/cron.d/{{name}}');
     });
     

3. CI/CD:

   • Validate cron syntax by dumping to a temporary file and parsing it in tests:

     $output = shell_exec('bin/console draw:cron:dump-to-file /tmp/cron.test');
     $this->assertStringContainsString('* * * * *', $output);
     

Integration Tips

• Logging: Append job-specific logging to the command (e.g., command: ">> /var/log/myapp_cron.log 2>&1").
• Environment Variables: Pass environment variables via the command:

  command: "%cron.console.execution% my:command --env=%kernel.environment% APP_ENV=%kernel.environment%"
  

• Dependencies: Use Laravel’s service container to dynamically resolve command paths or parameters:

  command: "@=service('kernel').getProjectDir().'/bin/console my:command'"
  

Gotchas and Tips

Pitfalls

1. File Permissions:

   • The dump command fails if the target file path is unwriteable. Ensure the web server user (e.g., www-data) has write permissions.
   • Fix: Use chmod 644 /etc/cron.d/your_app or deploy as root with sudo.

2. Parameter Resolution:

   • Undefined parameters (e.g., %cron.console.execution%) cause silent failures. Always define them in parameters.yaml:

     parameters:
         cron.console.execution: "php %kernel.project_dir%/bin/console"
     

3. Cron Syntax Errors:

   • Invalid expressions (e.g., */99 * * * *) are dumped as-is but may break cron. Validate expressions in tests or use a library like cron-validator.

4. Overwrite Behavior:

   • The command throws an exception if the file exists. Use --force (if available) or handle the exception in deployment scripts:

     bin/console draw:cron:dump-to-file /etc/cron.d/myapp || true
     

Debugging

• Dry Run: Dump to a temporary file (e.g., /tmp/cron.debug) and manually inspect the output before deploying.
• Parameter Dumping: Debug parameter resolution by dumping the container:

  bin/console debug:container --parameter=cron.console.execution
  

Extension Points

1. Custom Formatters:

   • Extend the bundle to support alternative formats (e.g., JSON for API-based cron management). Override the Draw\CronBundle\Command\DumpToFileCommand class.

2. Dynamic Job Loading:

   • Load jobs from a database or external API by implementing a JobLoader service and injecting it into the bundle’s CronManager.

3. Environment-Specific Files:

   • Use the enabled flag to route jobs to different files per environment:

     draw_cron:
         jobs:
             dev_job:
                 enabled: "%kernel.debug%"
                 output: ">/tmp/dev_cron.log"
             prod_job:
                 enabled: "!%kernel.debug%"
                 output: ">/var/log/prod_cron.log"
     

Tips

• Idempotency: Combine with a deployment tool (e.g., Ansible) to ensure the cron file is only updated when jobs change:

  # ansible-playbook.yml
  tasks:
      - name: Update cron file
        command: "bin/console draw:cron:dump-to-file /etc/cron.d/myapp"
        when: cron_jobs_changed.stat.exists and cron_jobs_changed.stat.mtime < now()
  

• Comments: Add metadata to the dumped file by including comments in the YAML:

  draw_cron:
      jobs:
          backup_job:
              description: "Daily backup at 2 AM"
              # Custom comment
              command: "php bin/console backup:run"
              expression: "0 2 * * *"
  

  Output:

  # Custom comment
  #Description: Daily backup at 2 AM
  0 2 * * * php bin/console backup:run