citrus-cms/resources/views/guide/REGISTER_CREATOR_FIX.md

Register Creator Queue System - Fix Summary

Problem Identified

The Register Creator queue system was experiencing the following issues:

1. RegisterCreatorJob failing immediately - Jobs were being processed but failing without clear error messages
2. No progress updates - Progress tracking wasn't working in queue context
3. Auth context missing - Auth::user() was being called in queue workers where no authenticated user exists
4. Slow PDF processing - pdftk commands were running without timeout, potentially hanging the system

Root Causes

1. Authentication Context Issue

The ProgressTracker class was calling Auth::user() in its addToQueue() method. In queue worker context, there's no authenticated user, causing the job to fail.

2. Missing User ID in Job Dispatch

The RegisterCreatorJob wasn't receiving the user ID, making it impossible to track who initiated the job.

3. Inefficient PDF Page Counting

The addRowInTable function was using shell_exec to run pdftk commands without:

• Timeout protection (could hang indefinitely)
• Caching (same files were being checked multiple times)
• Error output suppression

4. Progress Updates Not Visible

Progress updates weren't showing proper percentage or status information.

Solutions Implemented

1. Fixed ProgressTracker Authentication (app/Services/RegisterCreator/ProgressTracker.php)

// Before: Would crash in queue context
$user = Auth::user();

// After: Gracefully handles missing auth context
try {
    $user = Auth::user();
} catch (\Throwable $th) {
    $user = null;
    Log::warning("Could not get authenticated user in queue context");
}

2. Added User ID to RegisterCreatorJob (app/Jobs/RegisterCreatorJob.php)

// Added userId property
public int $userId;

// Constructor now accepts user ID
public function __construct(array $jobData, int $userId = null)
{
    $this->jobData = $jobData;
    $this->userId = $userId;
}

// User ID is now logged and tracked
$settings['tracking_user_id'] = $this->userId;

3. Updated Job Dispatch (app/Http/Controllers/RegisterCreatorController.php)

// Now passes user ID when dispatching
RegisterCreatorJob::dispatch($jobData, $u->id);

4. Optimized PDF Page Counting (app/Functions/addRowInTable.php)

// Added timeout to prevent hanging
$command = "timeout 5 pdftk {$allPath} dump_data 2>/dev/null | grep NumberOfPages";

// Added caching to prevent redundant checks
static $pageCountCache = [];
if (isset($pageCountCache[$cacheKey])) {
    $pageCount = $pageCountCache[$cacheKey];
}

5. Enhanced Progress Updates (app/Services/RegisterCreator/RegisterCreatorService.php)

// Now shows actual percentage and detailed descriptions
$progressPercent = (int) (($index + 1) / count($documents) * 100);
$this->progressTracker->update(
    "Processing document {$index + 1}/{$total}: {$docTitle}",
    $progressPercent
);

6. Added Error Resilience (app/Services/RegisterCreator/ProgressTracker.php)

// Progress tracking failures won't stop the job
try {
    Cache::put("register-creator-progress-{$this->jobId}", $progressData, ...);
} catch (\Throwable $th) {
    Log::error("Failed to update progress...");
}

Queue Worker Configuration

Started a dedicated queue worker with extended timeouts:

nohup php artisan queue:work database \
  --timeout=7200 \
  --tries=3 \
  --sleep=3 \
  --max-time=7200 \
  > /var/www/html/stellar2/storage/logs/queue-worker.log 2>&1 &

Parameters:

• --timeout=7200: Job can run up to 2 hours
• --tries=3: Retry failed jobs up to 3 times
• --sleep=3: Wait 3 seconds between jobs
• --max-time=7200: Worker restarts after 2 hours

Testing & Verification

To test the fixes:

1. Check if queue worker is running:

   ps aux | grep "queue:work"
   

2. Monitor queue worker log:

   tail -f /var/www/html/stellar2/storage/logs/queue-worker.log
   

3. Check job progress:

   php artisan tinker
   Cache::get('register-creator-queue')
   

4. Monitor Laravel logs:

   tail -f /var/www/html/stellar2/storage/logs/truncgil-$(date +%Y-%m-%d).log | grep -i register
   

Performance Improvements

1. PDF Processing: 5-second timeout prevents indefinite hanging
2. Caching: Page counts are cached, reducing redundant pdftk calls
3. Progress Updates: More informative with actual percentages
4. Error Handling: Jobs continue even if progress tracking fails

Next Steps

1. Monitor the queue worker for the next few hours
2. Check that progress updates are appearing in the UI
3. Verify that jobs complete successfully
4. Review Laravel logs for any new errors
5. Consider adding Redis for better queue performance (optional)

Additional Notes

• All code comments and text messages are in English as per project requirements
• The system now handles missing authentication context gracefully
• PDF processing has timeout protection to prevent hanging
• Progress tracking is non-blocking and won't stop job execution if it fails