Cron Translator Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require lorisleiva/cron-translator
   

   Add to composer.json under require if using a monorepo or constrained environment.

2. First Use Case: Translate a cron expression in a Laravel controller or service:

   use Lorisleiva\CronTranslator\CronTranslator;
   
   $translated = CronTranslator::translate('0 0 * * *'); // "Every day at 12:00am"
   return response()->json(['cron' => $translated]);
   

3. Where to Look First:

   • README.md: For basic usage, locales, and examples.
   • src/CronTranslator.php: Core logic and supported cron syntax.
   • tests/: Edge cases and validation patterns (e.g., */2, 1-5/3).

Implementation Patterns

Core Workflows

1. Admin Panels/Dashboards:

   • Display human-readable cron descriptions next to input fields or logs:

     // In a Laravel Blade view
     <div class="cron-description">
         {{ CronTranslator::translate($job->cronExpression, 'en') }}
     </div>
     

   • Tip: Cache translations for static cron expressions (e.g., system jobs) using Laravel’s cache:

     $translated = Cache::remember("cron_{$cron}", now()->addHours(1), function() use ($cron) {
         return CronTranslator::translate($cron);
     });
     

2. API Documentation:

   • Auto-generate Swagger/OpenAPI descriptions for cron-triggered endpoints:

     /**
      * @OA\Get(
      *     path="/webhooks/payment",
      *     summary="Process payment webhook",
      *     description="{{ CronTranslator::translate('0 9 * * 1-5', 'en') }}"
      * )
      */
     

3. User-Facing Scheduling Tools:

   • Validate and translate cron inputs in forms:

     // Laravel Form Request validation
     public function rules()
     {
         return [
             'cron_expression' => [
                 'required',
                 'string',
                 function ($attribute, $value, $fail) {
                     try {
                         CronTranslator::translate($value); // Throws on invalid cron
                     } catch (\InvalidArgumentException $e) {
                         $fail('Invalid cron expression.');
                     }
                 },
             ],
         ];
     }
     

4. Logging/Auditing:

   • Log human-readable cron triggers for debugging:

     Log::info('Scheduled job triggered', [
         'cron' => CronTranslator::translate($job->cron),
         'job' => $job->name,
     ]);
     

Integration Tips

• Localization:

  • Use Laravel’s locale system to dynamically pass the user’s locale:

    $locale = app()->getLocale();
    $translated = CronTranslator::translate($cron, $locale);
    

  • For 24-hour time format, pass true as the third argument:

    CronTranslator::translate('30 18 * * *', 'fr', true); // "Chaque jour à 18:30"
    

• Laravel Service Providers:

  • Bind the translator as a singleton for dependency injection:

    // app/Providers/AppServiceProvider.php
    public function register()
    {
        $this->app->singleton(CronTranslator::class);
    }
    

  • Use in controllers/services:

    public function __construct(private CronTranslator $translator) {}
    

• Testing:

  • Test translations in PHPUnit:

    public function testCronTranslation()
    {
        $this->assertEquals(
            'Every minute',
            CronTranslator::translate('* * * * *')
        );
    }
    

  • Test edge cases (e.g., */2, 1-5/3) from the package’s test suite.

• Extended Cron Support:

  • The package supports step values (*/2), ranges (1-5), lists (1,2,3), and comma-separated weekdays (1,2,3,4,5). Validate inputs against these patterns before translation.

Gotchas and Tips

Pitfalls

1. Unsupported Cron Syntax:

   • The package does not support cron extensions like:
     • L (last day of the month)
     • W (nearest weekday)
     • ? (no specific value, used in Quartz-style cron)
     • Yearly fields (e.g., * * * * * 2025).
   • Workaround: Pre-process or validate cron expressions to strip unsupported tokens.

2. Locale Fallback:

   • If a locale is unsupported, the package defaults to en. Always handle fallbacks:

     try {
         $translated = CronTranslator::translate($cron, $locale);
     } catch (\InvalidArgumentException $e) {
         $translated = CronTranslator::translate($cron); // Fallback to English
     }
     

3. Performance:

   • Translating complex cron expressions (e.g., 1,2 0 */2 1,2 *) can be CPU-intensive for large batches. Cache results aggressively:

     Cache::forever("cron_{$cron}_{$locale}", $translated);
     

4. Time Format Quirks:

   • The 24-hour flag (true) only affects the time portion of the output. Dates (e.g., "January 1st") remain in locale-specific formats.

5. Weekday Ambiguity:

   • Cron uses 0-6 for weekdays (0 = Sunday). The package handles this internally, but user inputs (e.g., forms) should validate against 0-6 or 1-7 (if using 1 = Monday).

Debugging Tips

1. Invalid Cron Expressions:

   • The package throws \InvalidArgumentException for malformed cron strings. Catch and log these for debugging:

     try {
         $translated = CronTranslator::translate($cron);
     } catch (\InvalidArgumentException $e) {
         Log::error("Invalid cron '{$cron}': " . $e->getMessage());
         throw new \RuntimeException('Invalid cron expression.');
     }
     

2. Unexpected Output:

   • For complex cron expressions (e.g., 1-3/5 * * * *), verify the output against crontab.guru or the Vixie cron format.
   • Example: 1-3/5 * * * * translates to "3 times every 5 minutes" (not "every 5 minutes from 1 to 3").

3. Locale-Specific Issues:

   • Some locales (e.g., ar, hi) may render dates in unexpected formats. Test with real user locales early:

     // Test all supported locales
     $locales = ['en', 'fr', 'ar', 'zh', 'pt'];
     foreach ($locales as $locale) {
         echo CronTranslator::translate('0 0 * * *', $locale) . "\n";
     }
     

Extension Points

1. Custom Locales:

   • Add new locales by extending the package’s translation system. Fork the repo or create a wrapper:

     // app/Services/CustomCronTranslator.php
     use Lorisleiva\CronTranslator\CronTranslator as BaseTranslator;
     
     class CustomCronTranslator extends BaseTranslator
     {
         public static function translate(string $cron, string $locale = 'en', bool $use24HourFormat = false): string
         {
             // Add custom logic here (e.g., override translations)
             return parent::translate($cron, $locale, $use24HourFormat);
         }
     }
     

2. Cron Validation:

   • Combine with spatie/cron-expression for validation:

     use Spatie\CronExpression\CronExpression;
     
     public function validateCron(string $cron): void
     {
         if (!CronExpression::isValidExpression($cron)) {
             throw new \InvalidArgumentException('Invalid cron expression.');
         }
     }
     

3. Laravel Artisan Commands:

   • Create a custom Artisan command to translate cron expressions:

     // app/Console/Commands/TranslateCron.php
     use Lorisleiva\CronTranslator\CronTranslator;
     
     class TranslateCron extends Command
     {
         protected $signature = 'cron:translate {cron} {--locale= : Language code} {--24-hour : Use 24-hour format}';
         protected $description = 'Translate a cron expression to human-readable text';
     
         public function handle()
         {
             $translated = CronTranslator::translate(
                 $this->argument('cron'),
                 $this->option('locale'),
                 $this->option('24-hour')
             );