Crontab Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require bentools/crontab-bundle:0.2.*
   

   (No additional config needed with Symfony Flex.)

2. Define Crontab Jobs: Create config/crontab.dist with entries like:

   # Run daily at midnight
   0 0 * * * php {%kernel.project_dir%}/bin/console app:daily-task
   

3. Preview Changes:

   php bin/console crontab:update --dry-run --dump
   

   Verify output matches expectations.

4. Apply:

   php bin/console crontab:update
   

   Confirm with crontab -l.

First Use Case

Schedule a Laravel command (e.g., app:cleanup) to run nightly:

0 3 * * * php {%kernel.project_dir%}/bin/console app:cleanup --force

Implementation Patterns

Workflows

1. Development Workflow:

   • Use --dry-run to test changes locally before deploying.
   • Store crontab.dist in version control (exclude actual crontab via .gitignore).

2. Deployment Workflow:

   • Commit crontab.dist to repo.
   • Run crontab:update post-deploy (via CI/CD or deployment script).

3. Dynamic Configuration:

   • Reference container parameters (e.g., {%env('APP_ENV')%}) for environment-specific paths.

Integration Tips

• Laravel Commands: Ensure commands are callable via CLI (e.g., php artisan app:command). Use absolute paths in crontab.dist (e.g., {%kernel.project_dir%}/bin/console).

• Environment Awareness: Use {%env('APP_ENV')%} to conditionally enable/disable jobs:

  {% if env('APP_ENV') == 'production' %}
  0 0 * * * php {%kernel.project_dir%}/bin/console app:backup
  {% endif %}
  

• Error Handling: Redirect output/errors to logs:

  0 0 * * * php {%kernel.project_dir%}/bin/console app:task >> /var/log/app_cron.log 2>&1
  

• Symfony Integration: Combine with symfony/process for complex job orchestration.

Gotchas and Tips

Pitfalls

1. Crontab Conflicts:

   • Warning: Overwrites the user’s entire crontab. Avoid if other processes manage it.
   • Fix: Backup existing crontab (crontab -l > backup.cron) before running crontab:update.

2. Path Resolution:

   • {%kernel.project_dir%} must resolve correctly. Test with:

     php bin/console debug:container --parameter kernel.project_dir
     

3. Permissions:

   • Crontab jobs run as the user executing crontab:update. Ensure:
     • The user has access to bin/console.
     • File permissions allow execution (e.g., chmod +x bin/console).

4. Template Parsing:

   • Only container parameters wrapped in {% ... %} are replaced. Raw text is treated literally.

5. Archived Package:

   • No active maintenance. Fork or migrate to alternatives like:
     • spatie/cron-to-expression (for parsing).
     • Custom scripts using crontab -l + echo redirection.

Debugging

• Dry Run Mismatches: Compare --dry-run --dump output with crontab -l after applying. Discrepancies may indicate:

  • Incorrect template syntax.
  • Missing container parameters.

• Command Failures: Check logs (/var/log/syslog or job-specific logs) for:

  • Missing dependencies (e.g., PHP not in $PATH).
  • Permission denied errors.

Tips

1. Idempotency: Use --force to overwrite existing entries:

   php bin/console crontab:update --force
   

2. Job Descriptions: Add comments to crontab.dist for clarity:

   # Daily backup at 2 AM (Production only)
   0 2 * * * php {%kernel.project_dir%}/bin/console app:backup
   

3. Testing: Simulate cron execution locally with:

   * * * * * php {%kernel.project_dir%}/bin/console app:test-job --simulate
   

4. Alternatives for Complex Setups:

   • Use symfony/process to trigger jobs via HTTP (e.g., Laravel queues).
   • For distributed systems, consider tools like Airflow or Beanstalkd.

5. Security: Restrict crontab:update to deploy users via:

   chmod 700 bin/console