Agent Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require horizonhub/agent
   

   Publish the config file:

   php artisan vendor:publish --provider="HorizonHub\Agent\AgentServiceProvider"
   

2. Configuration Edit config/horizonhub-agent.php with your Horizon Hub API credentials and queue connection details.

3. First Use Case Push a test event to Horizon Hub:

   use HorizonHub\Agent\Facades\Agent;
   
   Agent::push('job.processed', ['job_id' => 123]);
   

   Verify the event appears in your Horizon Hub dashboard.

Implementation Patterns

Event-Driven Workflows

• Queue Job Events Listen for job events (e.g., job.processed, job.failed) and push them to Horizon Hub:

  // In a job or event listener
  event(new JobProcessed($job));
  // Agent automatically pushes if configured
  

• Custom Events Extend the agent to handle custom events:

  Agent::push('custom.event', ['data' => $payload], ['metadata' => 'value']);
  

Integration with Laravel Queues

• Queue Listeners Use queue:listen with the agent to sync events in real-time:

  php artisan queue:listen --env=production --sleep=3 --tries=3
  

• Batch Processing For bulk events (e.g., after a migration), use:

  Agent::pushBatch([
      ['event' => 'job.processed', 'data' => ['id' => 1]],
      ['event' => 'job.processed', 'data' => ['id' => 2]],
  ]);
  

Middleware & Filtering

• Event Filtering Configure allowed events in config/horizonhub-agent.php:

  'allowed_events' => ['job.processed', 'job.failed'],
  

• Payload Transformation Use a custom payload formatter:

  Agent::setPayloadFormatter(function ($event, $data) {
      return ['event' => $event, 'data' => $data, 'timestamp' => now()];
  });
  

Gotchas and Tips

Common Pitfalls

• Authentication Errors Ensure HORIZONHUB_API_KEY and HORIZONHUB_API_SECRET are correctly set in .env or config. Debug: Check Horizon Hub API logs for rejected requests.

• Rate Limiting The agent respects Horizon Hub’s rate limits. Monitor config/horizonhub-agent.php for max_retries and delay.

• Event Duplication Use Laravel’s queue:failed table to track retries and avoid duplicates:

  Agent::push('job.processed', $data, ['dedupe_key' => $job->id]);
  

Debugging Tips

• Enable Logging Set debug to true in config to log API responses:

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

• Mock API Calls For testing, override the HTTP client:

  $agent = app(HorizonHub\Agent\Agent::class);
  $agent->setHttpClient(new MockHttpClient());
  

Extension Points

• Custom Transport Replace the default HTTP client for advanced use cases (e.g., WebSockets):

  Agent::setHttpClient(new CustomHttpClient());
  

• Webhook Fallback Combine with Laravel’s queue:after hook to fallback to webhooks if Horizon Hub is unavailable:

  Queue::after(function ($job, $data) {
      if (!$agent->push('job.processed', $data)) {
          // Fallback logic
      }
  });
  

• Environment-Specific Config Use environment variables for dynamic API endpoints:

  'api_url' => env('HORIZONHUB_API_URL', 'https://hub.example.com/api'),