Laravel Data Jobs Laravel Package

Getting Started

Start by installing the package via Composer:

composer require badrshs/laravel-data-jobs

Run the installation command to set up the database table:

php artisan data-jobs:install

First Use Case: Create a simple data migration command.

1. Generate a new Artisan command:

   php artisan make:command MigrateCustomerData
   

2. Add the DataJobable trait and define the migration logic:

   <?php
   namespace App\Console\Commands;
   
   use Illuminate\Console\Command;
   use Badrshs\LaravelDataJobs\Contracts\DataJobable;
   
   class MigrateCustomerData extends Command
   {
       use DataJobable;
   
       protected $signature = 'data:migrate-customers';
       protected $description = 'Migrate customer data to new schema';
   
       public function handle()
       {
           // Your migration logic here
           $this->info('Customer data migrated successfully!');
           return self::SUCCESS;
       }
   }
   

3. Run the job:

   php artisan data:run-jobs
   

Implementation Patterns

Workflows

1. Job Creation:

   • Use the DataJobable trait for all one-time data migration commands.
   • Define job priority with getJobPriority() (lower numbers run first).
   • Optionally set parameters with getJobParameters() for job-specific configurations.

2. Execution:

   • Run all pending jobs with:

     php artisan data:run-jobs
     

   • Run a specific job:

     php artisan data:run-jobs --job=MigrateCustomerData
     

   • Force re-run completed jobs:

     php artisan data:run-jobs --force
     

3. Tracking and Debugging:

   • Check job statuses in the data_jobs_log table.
   • Use the --verbose flag for detailed output:

     php artisan data:run-jobs --verbose
     

Integration Tips

• Laravel Queues: Integrate with Laravel’s queue system for asynchronous execution by dispatching jobs in the handle() method:

  public function handle()
  {
      dispatch(new MigrateCustomerDataJob());
  }
  

• Priority Management: Use priority to control execution order for dependent jobs:

  public function getJobPriority(): int
  {
      return 5; // Higher priority than default (100)
  }
  

• Conditional Execution: Disable jobs temporarily using isEnabled():

  public function isEnabled(): bool
  {
      return env('RUN_MIGRATIONS', false);
  }
  

• Custom Logging: Extend the logging mechanism by publishing the config and customizing the log_table or adding additional columns to the data_jobs_log table.

Gotchas and Tips

Pitfalls

1. Database Schema Conflicts:

   • Ensure the data_jobs_log table migration is run before executing jobs. If the table is missing, the package will throw an error.
   • Fix: Run php artisan migrate if the table is not created.

2. Job Discovery Issues:

   • The package automatically discovers commands using the DataJobable trait. If jobs aren’t running, verify:
     • The trait is correctly added to the command.
     • The command is registered in app/Console/Kernel.php.
   • Fix: Manually trigger discovery by clearing the cache:

     php artisan optimize:clear
     

3. Priority Collisions:

   • Jobs with the same priority may run in an unpredictable order.
   • Fix: Assign unique priorities to avoid collisions.

4. Logging Disabled:

   • If logging_enabled is set to false in the config, jobs will run without tracking.
   • Fix: Ensure logging_enabled is true in config/data-jobs.php for proper tracking.

Debugging

• Check Job Statuses:

  php artisan tinker
  

  \Badrshs\LaravelDataJobs\Models\DataJobLog::all();
  

• Verbose Output: Use the --verbose flag to see detailed execution logs:

  php artisan data:run-jobs --verbose
  

• Force Fresh Run: Clear existing logs and run jobs fresh:

  php artisan data:run-jobs --fresh
  

Extension Points

1. Custom Job Parameters: Extend the getJobParameters() method to pass dynamic data to jobs:

   public function getJobParameters(): array
   {
       return [
           'batch_size' => 1000,
           'start_date' => now()->subDays(7)
       ];
   }
   

2. Custom Status Handling: Override the default statuses (pending, running, completed, failed) by extending the DataJobLog model or adding custom columns to the data_jobs_log table.

3. Event Listeners: Add event listeners for job status changes by publishing the package’s event classes and registering listeners in EventServiceProvider:

   protected $listen = [
       \Badrshs\LaravelDataJobs\Events\JobStarted::class => [
           \App\Listeners\LogJobStart::class,
       ],
       \Badrshs\LaravelDataJobs\Events\JobCompleted::class => [
           \App\Listeners\NotifyJobCompletion::class,
       ],
   ];
   

4. Retry Mechanism: Implement a retry logic for failed jobs by catching exceptions in the handle() method and re-running the job:

   public function handle()
   {
       try {
           // Migration logic
       } catch (\Exception $e) {
           $this->error('Migration failed: ' . $e->getMessage());
           return self::FAILURE;
       }
   }
   

5. Environment-Specific Jobs: Use the isEnabled() method to control job execution based on environment variables:

   public function isEnabled(): bool
   {
       return app()->environment('production');
   }