Laravel Plugin Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require saloonphp/laravel-plugin
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Saloon\Laravel\SaloonServiceProvider"
   

2. Define Your First Connector Use the Artisan command to scaffold a connector:

   php artisan saloon:connector StripeConnector
   

   This generates:

   • app/Integrations/Stripe/StripeConnector.php (base connector)
   • app/Integrations/Stripe/Requests/ (for request classes)
   • app/Integrations/Stripe/Responses/ (for response classes)

3. First Use Case: Make an API Request

   use App\Integrations\Stripe\StripeConnector;
   
   $connector = new StripeConnector();
   $response = $connector->charge()->request([
       'amount' => 1000,
       'currency' => 'usd',
       'source' => 'tok_visa',
   ]);
   

Key Starting Points

• Documentation: SaloonPHP Official Docs (Laravel-specific sections under "Laravel Plugin").
• Artisan Commands:
  • saloon:connector – Generate a new connector.
  • saloon:request – Generate a request class.
  • saloon:list – List all registered connectors.
• Config: config/saloon.php (adjust integrations_path if needed).

Implementation Patterns

1. Connector Workflow

• Base Connector: Extend Saloon\Connector and define endpoints as methods.

  class StripeConnector extends Connector
  {
      public function charge(): Request
      {
          return $this->request()
              ->withPath('/v1/charges')
              ->withMethod('post');
      }
  }
  

• Request Classes: Use saloon:request to generate typed request classes.

  php artisan saloon:request StripeChargeRequest --connector=StripeConnector
  

  class StripeChargeRequest extends Request
  {
      public function resolveEndpoint(): string
      {
          return '/v1/charges';
      }
  
      public function resolveMethod(): string
      {
          return 'post';
      }
  
      public function resolveBody(): array
      {
          return [
              'amount' => $this->amount,
              'currency' => $this->currency,
              'source' => $this->source,
          ];
      }
  }
  

2. Response Handling

• Auto-Transform Responses: Use resolveData() in response classes.

  class StripeChargeResponse extends Response
  {
      public function resolveData(): array
      {
          return $this->data['data'];
      }
  }
  

• Typed Responses: Cast responses to DTOs or models.

  $response = $connector->charge()->resolve();
  $charge = $response->toModel(StripeCharge::class);
  

3. Authentication

• OAuth: Use the --oauth flag with saloon:connector.

  php artisan saloon:connector GitHubConnector --oauth
  

• API Keys: Bind keys to the container.

  $connector->withToken('Bearer ' . config('services.stripe.key'));
  

4. Laravel Integration

• Service Container: Bind connectors as singletons.

  $this->app->singleton(StripeConnector::class, function ($app) {
      return new StripeConnector();
  });
  

• Events: Dispatch events for API responses.

  $connector->charge()->then(function (StripeChargeResponse $response) {
      event(new ChargeCreated($response->data()));
  });
  

5. Testing

• Mocking: Use Saloon::fake() for contract testing.

  public function test_charge_creation()
  {
      Saloon::fake([
          StripeChargeRequest::class => [
              'id' => 'ch_123',
              'amount' => 1000,
          ],
      ]);
  
      $response = $this->stripe->charge()->request([...]);
      $this->assertEquals('ch_123', $response->id());
  }
  

• Nightwatch Middleware: Auto-mock responses in tests.

  use Saloon\Testing\Nightwatch;
  
  public function test_with_nightwatch()
  {
      Nightwatch::fake([
          StripeChargeRequest::class => [...],
      ]);
  
      // Test logic...
  }
  

6. Observability

• Telescope Integration: Log requests/responses to Laravel Telescope.

  $connector->withMiddleware(new TelescopeMiddleware());
  

• Pulse Integration: Monitor API performance with Laravel Pulse.

  $connector->withMiddleware(new PulseMiddleware());
  

Gotchas and Tips

Pitfalls

1. Integration Path Misconfiguration

   • If integrations_path in config/saloon.php is incorrect, Artisan commands fail.
   • Fix: Ensure the path points to a directory under app/ (e.g., app/Integrations).

     'integrations_path' => app_path('Integrations'),
     

2. Middleware Registration Duplicates

   • Nightwatch or Telescope middleware may register multiple times.
   • Fix: Use Saloon::once() or check for existing middleware in boot().

     if (! $this->app->bound('saloon.telescope')) {
         $this->app->singleton('saloon.telescope', fn() => new TelescopeMiddleware());
     }
     

3. Sensitive Data in Requests

   • Hardcoding secrets (e.g., API keys) in request classes leaks them.
   • Fix: Use Laravel’s binding or environment variables.

     public function resolveHeaders(): array
     {
         return [
             'Authorization' => 'Bearer ' . config('services.stripe.key'),
         ];
     }
     

4. PHP 8.5+ Deprecations

   • Some Saloon v3 features may not work with older PHP versions.
   • Fix: Ensure PHP 8.5+ and Saloon v4+ are used.

     composer require saloonphp/saloon:^4.0
     

5. Contract Testing Gaps

   • Mocking complex nested responses can be brittle.
   • Fix: Use partial mocks or Saloon::fake() with wildcards.

     Saloon::fake([
         StripeChargeRequest::class => [
             'id' => 'ch_*',
             'amount' => 1000,
         ],
     ]);
     

Debugging Tips

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

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

   Then check logs for raw request/response payloads.

2. Inspect Raw Responses Use dd($response->raw()) to debug unparsed responses.

3. Telescope Debugging

   • Ensure saloon.telescope middleware is registered.
   • Check the "Requests" tab in Telescope for API call details.

4. Nightwatch Assertions Verify mocks are applied:

   Nightwatch::assertSent(StripeChargeRequest::class);
   

Extension Points

1. Custom Middleware Extend Saloon\ConnectorMiddleware for reusable logic (e.g., rate limiting).

   class RateLimitMiddleware extends ConnectorMiddleware
   {
       public function handle(Request $request, callable $next)
       {
           if ($request->getRateLimit() > 0) {
               // Logic...
           }
           return $next($request);
       }
   }
   

2. Dynamic Connectors Use Laravel’s container to resolve connectors dynamically.

   $connector = $this->app->make($request->connectorClass);
   

3. Contract Testing Extensions Override Saloon::fake() behavior for custom assertions.

   Saloon::extend(function ($connector) {
       $connector->fakeCallback = fn($request) => [...];
   });
   

4. IDE Support Use the ide.json file for autocompletion in connectors/requests. Example:

   {
       "namespaces": {
           "App\\Integrations\\*\\*": "app/Integrations"
       }
   }
   

Performance Tips

1. Reuse Connectors Bind connectors as singletons to avoid reinitializing clients.

   $this->app->singleton(StripeConnector::class);
   

2. Lazy-Load Requests Use `->