Laravel Plugin Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require saloonphp/laravel-plugin
   

   Publish the config (optional):

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

2. First Use Case: HTTP Client Define a connector (e.g., GitHubConnector):

   use Saloon\Contracts\Connector;
   use Saloon\Saloon;
   
   class GitHubConnector extends Connector
   {
       protected string $baseUrl = 'https://api.github.com';
       protected string $tokenName = 'github_token';
   }
   

   Register it in config/saloon.php:

   'connectors' => [
       'github' => [
           'class' => \App\Connectors\GitHubConnector::class,
       ],
   ],
   

3. First Request

   use Saloon\Laravel\Facades\Saloon;
   
   $response = Saloon::connect('github')->call(new GetUserRequest('octocat'));
   $user = $response->json();
   

Implementation Patterns

1. Request/Response Workflows

• Define Requests (e.g., GetUserRequest):

  use Saloon\Contracts\Request;
  
  class GetUserRequest extends Request
  {
      public function resolveEndpoint(): string
      {
          return '/users/' . $this->username;
      }
  }
  

• Handle Responses (e.g., GetUserResponse):

  use Saloon\Contracts\Response;
  
  class GetUserResponse extends Response
  {
      public function resolve(): array
      {
          return $this->data['data'];
      }
  }
  

2. Authentication & Middleware

• Token-Based Auth (via tokenName in connector):

  protected string $tokenName = 'github_token'; // Fetches from Laravel config
  

• Custom Middleware (e.g., logging):

  use Saloon\Contracts\Middleware;
  
  class LogRequestMiddleware implements Middleware
  {
      public function handle($request): void
      {
          \Log::info('Request:', $request->toArray());
      }
  }
  

  Register in config/saloon.php:

  'middleware' => [
      \App\Middleware\LogRequestMiddleware::class,
  ],
  

3. Integration with Laravel Services

• Dependency Injection:

  use Saloon\Laravel\Facades\Saloon;
  
  class UserService
  {
      public function __construct(private Saloon $saloon) {}
  
      public function fetchUser(string $username)
      {
          return $this->saloon->connect('github')->call(new GetUserRequest($username));
      }
  }
  

• Caching Responses (via Laravel Cache):

  use Saloon\Contracts\Cache;
  
  class CacheMiddleware implements Middleware
  {
      public function handle($request): void
      {
          $cacheKey = 'github_user_' . $request->username;
          if (cache()->has($cacheKey)) {
              $request->response = cache()->get($cacheKey);
          }
      }
  }
  

4. Testing

• Mocking Connectors:

  $connector = new GitHubConnector();
  $connector->mockResponse(new GetUserResponse(['id' => 123]));
  
  $response = $connector->call(new GetUserRequest('octocat'));
  

• Pest/Unit Tests:

  it('fetches a user', function () {
      $connector = new GitHubConnector();
      $connector->mockResponse(new GetUserResponse(['login' => 'octocat']));
  
      $response = $connector->call(new GetUserRequest('octocat'));
      expect($response->login)->toBe('octocat');
  });
  

Gotchas and Tips

Pitfalls

1. Token Management:

   • Ensure tokenName in the connector matches a key in config/services.php (e.g., github.token).
   • Fix: Verify config/saloon.php and config/services.php alignment.

2. Response Parsing:

   • Saloon expects JSON by default. For non-JSON APIs (e.g., XML), override resolve() in the response class.
   • Fix:

     class XmlResponse extends Response
     {
         public function resolve(): array
         {
             return json_decode(json_encode(simplexml_load_string($this->body)), true);
         }
     }
     

3. Middleware Order:

   • Middleware runs in registration order. Place CacheMiddleware after LogMiddleware to avoid logging cached responses.
   • Fix: Reorder in config/saloon.php.

4. Rate Limiting:

   • Saloon doesn’t enforce rate limits by default. Use Laravel’s throttle middleware or a custom Saloon middleware.
   • Fix:

     class RateLimitMiddleware implements Middleware
     {
         public function handle($request): void
         {
             if ($request->connector->rateLimitExceeded()) {
                 throw new \Exception('Rate limit exceeded');
             }
         }
     }
     

Debugging Tips

• Enable Debug Mode:

  Saloon::debug(); // Logs all requests/responses to Laravel logs.
  

• Inspect Raw Responses:

  $response = Saloon::connect('github')->call(new GetUserRequest('octocat'));
  \Log::info('Raw:', $response->raw());
  

Extension Points

1. Custom Connectors:

   • Extend Saloon\Connector for non-HTTP protocols (e.g., WebSocket).
   • Example:

     class WebSocketConnector extends Connector
     {
         protected function sendRequest(): void
         {
             // Custom WebSocket logic
         }
     }
     

2. Dynamic Config:

   • Override connector config per request:

     $connector = new GitHubConnector();
     $connector->setBaseUrl('https://api.github.com/v3'); // Override dynamically
     

3. Event Listeners:

   • Listen to saloon.request and saloon.response events:

     Saloon::listen(function ($request) {
         \Log::info('Request fired:', $request->method);
     });
     

Performance

• Batch Requests: Use Saloon::batch() for parallel calls:

  $responses = Saloon::batch([
      new GetUserRequest('octocat'),
      new GetUserRequest('laravel'),
  ]);
  

• Connection Pooling: Reuse connectors for multiple requests to avoid reconnecting:

  $connector = new GitHubConnector();
  $response1 = $connector->call(new GetUserRequest('octocat'));
  $response2 = $connector->call(new GetRepoRequest('laravel'));