Laravel Schedulable Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require neelkanthk/laravel-schedulable
   

   Publish the migration (if using custom column names):

   php artisan vendor:publish --provider="Neelkanth\LaravelSchedulable\LaravelSchedulableServiceProvider" --tag="migrations"
   php artisan migrate
   

2. Apply the Trait: Add Schedulable trait to your Eloquent model:

   use Neelkanth\LaravelSchedulable\Schedulable;
   
   class Task extends Model
   {
       use Schedulable;
   }
   

3. First Use Case: Schedule a model for a future time:

   $task = Task::create(['name' => 'Quarterly Report']);
   $task->scheduleAt(Carbon::now()->addDays(30)); // Schedule for 30 days later
   

Implementation Patterns

Core Workflows

1. Scheduling Models:

   // Schedule for a specific Carbon instance
   $model->scheduleAt(Carbon::now()->addHours(2));
   
   // Schedule for a relative time (uses Carbon's syntax)
   $model->scheduleAt('+1 week');
   

2. Querying Scheduled Models:

   // Get all scheduled models (active or future)
   $scheduledModels = Task::scheduled()->get();
   
   // Get only active scheduled models (not yet executed)
   $activeModels = Task::scheduled()->active()->get();
   
   // Get models scheduled for a specific time
   $modelsAtTime = Task::scheduled()->at(Carbon::now())->get();
   

3. Rescheduling/Unscheduling:

   // Reschedule to a new time
   $model->rescheduleAt(Carbon::now()->addDays(7));
   
   // Unschedule (sets scheduled_at to null)
   $model->unschedule();
   

4. Lifecycle Hooks: Override default events in your model:

   protected static function scheduled($model)
   {
       // Runs when a model is scheduled
       Log::info("Model {$model->id} scheduled for {$model->scheduled_at}");
   }
   
   protected static function unscheduled($model)
   {
       // Runs when a model is unscheduled
   }
   
   protected static function executed($model)
   {
       // Runs when a model's scheduled time is reached
   }
   

Integration Tips

• Queue Jobs: Combine with Laravel Queues to execute logic when executed() fires:

  protected static function executed($model)
  {
      dispatch(new ProcessTaskJob($model));
  }
  

• Soft Deletes: Works seamlessly with SoftDeletes trait.
• Scopes: Extend the package’s query scopes:

  public function scopeUpcoming($query)
  {
      return $query->scheduled()->where('scheduled_at', '>', now());
  }
  

Gotchas and Tips

Pitfalls

1. Timezone Handling: Ensure scheduled_at uses the correct timezone (default: app timezone). Explicitly set timezone when scheduling:

   $model->scheduleAt(Carbon::now()->setTimezone('UTC')->addHours(2));
   

2. Database Indexing: The scheduled_at column should be indexed for performance:

   Schema::table('tasks', function (Blueprint $table) {
       $table->dateTime('scheduled_at')->nullable()->index();
   });
   

3. Race Conditions: The executed() event fires when the query fetches models with scheduled_at <= now(). In high-traffic apps, consider:

   • Using a lock (e.g., Laravel\Queue\InteractsWithQueue) in executed().
   • Running a separate "sweeper" job to process models in batches.

4. Custom Column Names: If overriding the default scheduled_at column, ensure the trait’s config is updated:

   'column' => 'custom_schedule_time',
   

   in config/laravel-schedulable.php.

Debugging

• Check Scheduled Models:

  Task::scheduled()->dd(); // Debug all scheduled models
  

• Event Logs: Override lifecycle methods to log actions (e.g., protected static function scheduled($model)).

Extension Points

1. Custom Logic on Execution: Extend the executed() method to trigger additional actions:

   protected static function executed($model)
   {
       if ($model->isHighPriority()) {
           notifyAdmins($model);
       }
   }
   

2. Batch Processing: Create a command to process all overdue models:

   php artisan schedule:process --overdue
   

   (Requires custom implementation; the package doesn’t include this out-of-the-box.)

3. Soft Unscheduling: Modify the unschedule() method to mark models as "completed" instead of nulling scheduled_at:

   public function unschedule()
   {
       $this->update(['scheduled_at' => null, 'status' => 'completed']);
   }