Fasti Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require a-bashtannik/fasti
   php artisan vendor:publish --provider="Bashtannik\Fasti\FastiServiceProvider"
   php artisan migrate
   

   • Publishes config (config/fasti.php) and creates a scheduled_jobs table.

2. First Use Case: Schedule a job for a specific datetime:

   use Bashtannik\Fasti\Facades\Fasti;
   use App\Jobs\SendWelcomeEmail;
   
   $job = new SendWelcomeEmail($userId);
   Fasti::schedule($job, now()->addHours(1)); // Runs in 1 hour
   

3. Run the Scheduler: Add to your app/Console/Kernel.php:

   protected function schedule(Schedule $schedule)
   {
       $schedule->command('fasti:run')->everyMinute();
   }
   

Implementation Patterns

Core Workflows

1. Scheduling Jobs:

   • Basic Scheduling:

     Fasti::schedule(new ProcessOrder($order), now()->addMinutes(5));
     

   • With Payload:

     Fasti::schedule(new NotifyUser($user), now()->addDay(), ['priority' => 'high']);
     

2. Listing/Canceling Jobs:

   // List pending jobs
   $pendingJobs = Fasti::pending()->get();
   
   // Cancel a job by ID
   Fasti::cancel($jobId);
   

3. Queue vs. Sync Execution:

   • Defaults to queue (uses Laravel’s queue system).
   • Force synchronous execution:

     Fasti::schedule($job, $datetime, [], true); // 4th param = $sync
     

4. Recurring Tasks (via Laravel Scheduler):

   • Use fasti:run command in Schedule facade for periodic checks:

     $schedule->command('fasti:run')->everyFiveMinutes();
     

Integration Tips

1. Job Serialization:

   • Ensure your job implements ShouldQueue or is serializable.
   • For complex payloads, use serialize() or Laravel’s dispatchSync() for sync jobs.

2. Timezones:

   • Configure timezone in config/fasti.php (defaults to app timezone).
   • Pass Carbon instances or DateTime objects for consistency.

3. Error Handling:

   • Failed jobs are retried via Laravel’s queue system (configurable in .env).
   • Log failures in handleFailure() (override Bashtannik\Fasti\Jobs\ScheduledJob).

4. Testing:

   • Mock Fasti facade or use Fasti::fake() (if supported) for unit tests.
   • Test time-sensitive logic with travel() in PHPUnit:

     $this->travelTo($scheduledTime)->runQueuedJobs();
     

Gotchas and Tips

Pitfalls

1. Time Precision:

   • Issue: Jobs scheduled for the same second may overlap or fail due to race conditions.
   • Fix: Add a small offset (e.g., now()->addSeconds(1)) or use unique timestamps.

2. Queue Workers:

   • Issue: If queue workers aren’t running, scheduled jobs won’t execute.
   • Fix: Ensure php artisan queue:work is running (or use supervisor/foreman).

3. Database Locks:

   • Issue: High-frequency scheduling may cause table locks.
   • Fix: Batch jobs or increase DB_CONNECTION timeout in .env.

4. Timezone Mismatches:

   • Issue: Jobs may run at unexpected times if timezone settings differ.
   • Fix: Explicitly set timezone in config/fasti.php or pass Carbon-aware datetimes.

Debugging

1. Check Pending Jobs:

   php artisan fasti:list
   

   • Outputs all scheduled jobs with IDs/datetimes.

2. Log Execution:

   • Enable debug mode in config/fasti.php:

     'debug' => env('FASTI_DEBUG', false),
     

   • Logs appear in storage/logs/laravel.log.

3. Manual Trigger:

   • Force-run pending jobs:

     php artisan fasti:run --force
     

Extension Points

1. Custom Job Repository:

   • Extend Bashtannik\Fasti\Repositories\JobRepository to add fields (e.g., user_id).
   • Publish and modify migrations:

     php artisan vendor:publish --tag=fasti-migrations
     

2. Event Listeners:

   • Listen for job events (e.g., ScheduledJobCreated):

     use Bashtannik\Fasti\Events\ScheduledJobCreated;
     
     ScheduledJobCreated::listen(function ($job) {
         Log::info("Job {$job->id} scheduled for {$job->runs_at}");
     });
     

3. API Endpoints:

   • Create routes for CRUD operations:

     Route::get('/scheduled-jobs', [FastiController::class, 'index']);
     

   • Use Fasti::pending()/Fasti::cancel() in controllers.

4. Custom Commands:

   • Extend FastiCommand to add subcommands (e.g., fasti:reschedule).