Laravel Sync Tracker Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require andreagroferreira/laravel-sync-tracker
   

   Publish the config file:

   php artisan vendor:publish --provider="AndreaGroferreira\SyncTracker\SyncTrackerServiceProvider" --tag="config"
   

2. Configuration:

   • Review config/sync-tracker.php for default settings (e.g., sync_models, sync_queues, redis_connection).
   • Define your tracked models in the sync_models array:

     'sync_models' => [
         \App\Models\User::class,
         \App\Models\Product::class,
     ],
     

3. First Use Case: Track a sync operation for a User model:

   use AndreaGroferreira\SyncTracker\Facades\SyncTracker;
   
   $user = \App\Models\User::find(1);
   SyncTracker::track($user, 'sync_to_external_api', [
       'source' => 'laravel',
       'status' => 'pending',
       'metadata' => ['user_id' => $user->id],
   ]);
   

Implementation Patterns

Core Workflows

1. Tracking Sync Operations:

   • Use SyncTracker::track() to log sync attempts:

     SyncTracker::track($model, 'sync_operation_name', [
         'status' => 'completed',
         'attempts' => 3,
         'last_error' => null,
     ]);
     

   • Best Practice: Pass a unique operation_name (e.g., sync_to_stripe, push_to_salesforce).

2. Querying Sync Status:

   • Fetch sync history for a model:

     $history = SyncTracker::history($user);
     

   • Filter by status or operation:

     $failedSyncs = SyncTracker::history($user)
         ->where('status', 'failed')
         ->get();
     

3. Queue-Based Syncs:

   • Dispatch sync jobs with SyncTracker::dispatchSyncJob():

     SyncTracker::dispatchSyncJob($user, SyncToExternalApiJob::class, 'sync_to_external_api');
     

   • Tip: Use this for async operations (e.g., webhooks, batch processing).

4. Model Observers:

   • Extend SyncTrackerObserver for automatic tracking:

     use AndreaGroferreira\SyncTracker\Observers\SyncTrackerObserver;
     
     class UserObserver extends SyncTrackerObserver
     {
         public function syncing(User $user, string $operation)
         {
             // Custom logic before sync
         }
     
         public function synced(User $user, string $operation, array $result)
         {
             // Custom logic after sync
         }
     }
     

   • Register the observer in AppServiceProvider:

     User::observe(SyncTrackerObserver::class);
     

5. Redis Stream Integration:

   • Consume sync events in real-time via Redis streams:

     $consumer = app(\AndreaGroferreira\SyncTracker\Redis\SyncStreamConsumer::class);
     $consumer->consume('sync-tracker-stream', function ($message) {
         // Handle sync event (e.g., update UI, trigger alerts)
     });
     

Integration Tips

1. Sync Job Design:

   • Extend SyncTrackerJob for custom jobs:

     use AndreaGroferreira\SyncTracker\Jobs\SyncTrackerJob;
     
     class SyncToStripeJob extends SyncTrackerJob
     {
         public function handle()
         {
             try {
                 $this->sync();
                 $this->markAsSynced();
             } catch (\Exception $e) {
                 $this->markAsFailed($e->getMessage());
             }
         }
     }
     

2. API Endpoints:

   • Expose sync status via API:

     Route::get('/sync/status/{model}/{id}', function ($model, $id) {
         $instance = app($model)->findOrFail($id);
         return SyncTracker::history($instance)->latest()->first();
     });
     

3. Webhook Triggers:

   • Use SyncTracker::triggerWebhook() to notify external systems:

     SyncTracker::triggerWebhook($user, 'sync_completed', [
         'url' => 'https://external-api.com/webhook',
         'data' => ['user_id' => $user->id],
     ]);
     

4. Batch Processing:

   • Track batch syncs with a parent ID:

     SyncTracker::trackBatch($users, 'sync_all_users', [
         'total' => $users->count(),
         'completed' => 0,
     ]);
     

Gotchas and Tips

Common Pitfalls

1. Redis Connection Issues:

   • Ensure the redis_connection in config/sync-tracker.php matches your Laravel Redis config.
   • Debug: Check Redis logs if sync events aren’t appearing:

     redis-cli MONITOR
     

2. Model Not Tracked:

   • Verify the model is listed in sync_models and the observer is registered.
   • Fix: Run:

     php artisan sync-tracker:install
     

3. Duplicate Entries:

   • Use unique operation_name + model_id combinations to avoid duplicates.
   • Tip: Add a uuid to metadata if needed:

     SyncTracker::track($user, 'sync_to_api', [
         'uuid' => Str::uuid()->toString(),
     ]);
     

4. Queue Stuck Jobs:

   • Monitor failed jobs in failed_jobs table and retry manually:

     php artisan queue:retry all
     

5. Performance:

   • Avoid tracking overly granular operations (e.g., track "sync_user_profile" instead of "sync_user_email").
   • Optimization: Use SyncTracker::bulkTrack() for high-volume operations:

     SyncTracker::bulkTrack($users->toArray(), 'sync_users');
     

Debugging Tips

1. Log Sync Events:

   • Enable debug mode in config:

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

   • Check Laravel logs for SyncTracker entries.

2. Redis Stream Debugging:

   • List stream groups:

     redis-cli XGROUP LIST sync-tracker-stream consumer-group
     

   • Read pending messages:

     redis-cli XREADGROUP GROUP consumer-group COUNT 1 BLOCK 0 STREAMS sync-tracker-stream 0
     

3. Query Builder:

   • Use SyncTracker::query() for custom queries:

     $recentSyncs = SyncTracker::query()
         ->where('model_type', User::class)
         ->where('status', 'failed')
         ->where('created_at', '>', now()->subHours(1))
         ->get();
     

Extension Points

1. Custom Storage:

   • Override the default Redis storage by binding SyncTrackerRepository:

     $this->app->bind(\AndreaGroferreira\SyncTracker\Repositories\SyncTrackerRepository::class, function ($app) {
         return new CustomSyncTrackerRepository();
     });
     

2. Event Listeners:

   • Listen for SyncTracked events:

     event(new SyncTracked($user, 'sync_to_api', $data));
     

   • Register in EventServiceProvider:

     protected $listen = [
         \AndreaGroferreira\SyncTracker\Events\SyncTracked::class => [
             \App\Listeners\LogSyncEvent::class,
         ],
     ];
     

3. Custom Statuses:

   • Extend the status field with custom values (e.g., processing, queued):

     SyncTracker::track($user, 'sync_to_api', ['status' => 'processing']);
     

4. Webhook Signatures:

   • Validate webhook payloads by extending SyncWebhookValidator:

     class CustomWebhookValidator extends SyncWebhookValidator
     {
         public function validate(array $payload): bool
         {
             // Custom validation logic
             return true;
         }
     }
     

   • Bind the validator in AppServiceProvider:

     $this->app->bind(\AndreaGroferreira\SyncTracker\Contracts\SyncWebhookValidator::class, CustomWebhookValidator::class);