Symfony Client Laravel Package

Getting Started

Minimal Setup for Laravel Integration

1. Install the Package:

   composer require 1pilotapp/symfony-client:^2.0
   

   Note: While this package targets Symfony, Laravel can leverage it via Symfony’s HTTP client or by treating it as a monitoring agent.

2. Configure Environment: Add to .env:

   ONE_PILOT_PRIVATE_KEY=your_random_alphanumeric_key  # Generate via 1Pilot dashboard
   ONE_PILOT_MAIL_FROM_ADDRESS=no-reply@yourdomain.com  # Must match your app’s mail sender
   

3. Add Configuration: Create config/one_pilot.php (Laravel-style):

   return [
       'private_key' => env('ONE_PILOT_PRIVATE_KEY'),
       'mail_from_address' => env('ONE_PILOT_MAIL_FROM_ADDRESS'),
       'skip_timestamp_validation' => env('ONE_PILOT_SKIP_TIMESTAMP', false), // For dev only
   ];
   

4. Register Routes: Add to routes/web.php (or routes/api.php):

   Route::prefix('/1pilot')->group(function () {
       \OnePilot\ClientBundle\DependencyInjection\OnePilotClientExtension::loadRoutes();
   });
   

5. First Use Case:

   • Register your Laravel site in the 1Pilot dashboard.
   • Verify uptime monitoring, SSL checks, and Composer updates appear in the dashboard within minutes.

Implementation Patterns

Core Workflows

1. Monitoring Agent Integration:

   • Uptime Checks: The package adds a /1pilot/health endpoint. Call it periodically from Laravel’s scheduler:

     // app/Console/Kernel.php
     protected function schedule(Schedule $schedule) {
         $schedule->call(function () {
             Http::get('https://your-app.com/1pilot/health');
         })->everyMinute();
     }
     

   • Custom Metrics: Extend via Laravel’s events:

     // app/Providers/EventServiceProvider.php
     public function boot() {
         event(new \OnePilot\ClientBundle\Event\CustomMetricEvent(
             'laravel_custom_metric',
             ['value' => app()->version()]
         ));
     }
     

2. Email Verification:

   • Use the built-in email verification tool to validate your Laravel mail sender:

     // In a mailable or controller
     Mail::to('user@example.com')->send(new VerificationEmail());
     // 1Pilot will auto-detect and log the email.
     

3. Composer Updates:

   • Sync Composer updates to 1Pilot via Laravel’s composer.json events:

     // app/Providers/AppServiceProvider.php
     public function boot() {
         Composer::updating(function ($event) {
             \OnePilot\ClientBundle\Composer\ComposerUpdater::sync($event->getLock());
         });
     }
     

Laravel-Specific Patterns

1. Service Container Binding: Bind the 1Pilot client to Laravel’s container for DI:

   // app/Providers/AppServiceProvider.php
   public function register() {
       $this->app->singleton(\OnePilot\ClientBundle\Client::class, function ($app) {
           return new \OnePilot\ClientBundle\Client(
               $app['config']['one_pilot.private_key'],
               $app['config']['one_pilot.mail_from_address']
           );
       });
   }
   

2. Middleware for API Calls: Add 1Pilot headers to outgoing API requests:

   // app/Http/Middleware/Add1PilotHeaders.php
   public function handle($request, Closure $next) {
       $response = $next($request);
       $response->headers->set('X-1Pilot-Site-ID', config('one_pilot.site_id'));
       return $response;
   }
   

3. Artisan Commands: Create a command to manually trigger syncs:

   // app/Console/Commands/Sync1Pilot.php
   public function handle() {
       $client = app(\OnePilot\ClientBundle\Client::class);
       $client->syncAll();
       $this->info('Synced with 1Pilot!');
   }
   

Gotchas and Tips

Common Pitfalls

1. Private Key Mismatch:

   • Symptom: "Authentication failed" in 1Pilot dashboard.
   • Fix: Regenerate the key in the 1Pilot dashboard and update .env. Ensure the key is exactly the same (case-sensitive).

2. Time Synchronization Issues:

   • Symptom: "Timestamp validation failed" errors.
   • Fix: Either:
     • Sync your server time (ntpdate pool.ntp.org), or
     • Set skip_timestamp_validation: true in config (dev only).

3. Email Verification Failures:

   • Symptom: Emails sent via Laravel don’t appear in 1Pilot.
   • Fix:
     • Ensure ONE_PILOT_MAIL_FROM_ADDRESS matches the From address in your Laravel mailer.
     • Test with a simple email:

       Mail::raw('Test email for 1Pilot', function ($message) {
           $message->to('user@example.com')->from(config('one_pilot.mail_from_address'));
       });
       

4. Route Conflicts:

   • Symptom: 404 errors on /1pilot/* endpoints.
   • Fix: Ensure routes are loaded before Laravel’s default routes. In routes/web.php:

     Route::prefix('/1pilot')->group(function () {
         \OnePilot\ClientBundle\DependencyInjection\OnePilotClientExtension::loadRoutes();
     });
     Route::get('/', function () { ... }); // Other routes
     

5. Composer Lock File Sync:

   • Symptom: Composer updates not appearing in 1Pilot.
   • Fix: Manually trigger a sync after composer update:

     php artisan sync:1pilot
     

Debugging Tips

1. Enable Verbose Logging: Add to config/one_pilot.php:

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

   Check Laravel logs (storage/logs/laravel.log) for 1Pilot-related errors.

2. API Request Inspection: Use Laravel’s Http facade to inspect 1Pilot API calls:

   $response = Http::withHeaders([
       'Authorization' => 'Bearer ' . config('one_pilot.private_key'),
   ])->get('https://api.1pilot.io/v1/site/verify');
   

3. Disable Features Temporarily: Override config in bootstrap/app.php:

   $app->configure('one_pilot', function ($config) {
       $config['skip_timestamp_validation'] = true;
       $config['disable_composer_sync'] = true;
   });
   

Extension Points

1. Custom Events: Extend the CustomMetricEvent to send Laravel-specific metrics:

   // app/Events/Custom1PilotMetric.php
   class Custom1PilotMetric implements ShouldBroadcast {
       public function __construct(
           public string $name,
           public array $data,
           public ?int $siteId = null
       ) {}
   }
   

2. Webhook Listeners: Listen for 1Pilot webhooks (e.g., downtime alerts) in Laravel:

   // routes/web.php
   Route::post('/1pilot/webhook', [WebhookController::class, 'handle']);
   

3. Database Sync: Sync Laravel’s database schema changes to 1Pilot:

   // app/Providers/AppServiceProvider.php
   public function boot() {
       Schema::defaultStringLength(191);
       \OnePilot\ClientBundle\Database\DatabaseSync::syncSchema();
   }
   

Performance Considerations

• Rate Limiting: 1Pilot’s API has rate limits. Throttle syncs in Laravel:

  // app/Console/Kernel.php
  $schedule->command('sync:1pilot')->hourlyAt(30);
  

• Batch Processing: For large Composer dependencies, batch syncs:

  $client->syncComposerPackages(array_slice($packages, 0, 50));