Laravel Plugin Laravel Package

Technical Evaluation

Architecture Fit

• HTTP Client Abstraction: The package provides a clean, fluent API for HTTP requests (REST, GraphQL, SOAP) via Saloon, aligning well with Laravel’s service-oriented architecture. It abstracts Guzzle/HTTP client logic, reducing boilerplate and enforcing consistency.
• Laravel Ecosystem Synergy: Integrates natively with Laravel’s service container, configuration system, and HTTP middleware stack (e.g., app/Http/Middleware/). Supports Laravel’s event system (e.g., HttpClientRequested) for observability.
• Domain-Driven Design (DDD) Support: Encourages organizing HTTP clients as Saloon "Connectors" (e.g., StripeConnector, GitHubConnector), mapping to Laravel’s repositories or services layer. Aligns with hexagonal architecture principles.
• Testing Facade: Built-in mocking (MockConnector) simplifies unit/integration testing, critical for Laravel’s test-driven workflows.

Integration Feasibility

• Low Friction: Zero-configuration for basic use; minimal setup for advanced features (e.g., retries, circuit breakers). Compatible with Laravel’s config/app.php for HTTP client defaults.
• Middleware Compatibility: Supports Laravel’s HTTP middleware (e.g., Authenticate, ThrottleRequests) via Saloon’s withMiddleware() or global Saloon::extend().
• Queue/Job Integration: Saloon’s shouldQueue() and Laravel’s Bus/Jobs integrate seamlessly for async requests (e.g., webhooks, background syncs).
• Caching: Leverages Laravel’s cache drivers (Redis, file, etc.) via Saloon’s cache() decorator or Saloon::cache().

Technical Risk

• Version Lock: Saloon v2+ (released 2026) may introduce breaking changes if Laravel upgrades PHP (e.g., 8.3+ features). Risk mitigated by MIT license and active maintenance.
• Overhead for Simple APIs: For trivial endpoints, Saloon’s abstraction might feel heavy. Mitigate by using it only for complex APIs (e.g., GraphQL, OAuth).
• Debugging Complexity: Nested connectors/middleware could obscure request flows. Mitigate with Saloon’s built-in logging (Saloon::debug()) or Laravel’s tap().
• SOAP/GraphQL Learning Curve: If the team lacks experience with these protocols, ramp-up time may increase. Mitigate with Saloon’s documentation and Laravel’s IDE support (e.g., PHPStorm stubs).

Key Questions

1. API Complexity: Are most APIs RESTful, or do we heavily use GraphQL/SOAP? (Affects connector design.)
2. Auth Strategy: How is authentication handled (API tokens, OAuth, JWT)? Saloon supports all but may need custom middleware.
3. Observability: Do we need request logging/auditing? Saloon integrates with Laravel’s logging but may require custom event listeners.
4. Performance: Will async queues or caching be needed for high-volume endpoints?
5. Team Skills: Is the team familiar with Saloon’s fluent API, or will training be required?

Integration Approach

Stack Fit

• Laravel Core: Seamless integration with:
  • Service Container: Bind connectors as singletons ($this->app->bind(StripeConnector::class, fn() => new StripeConnector())).
  • Configuration: Extend config/saloon.php for global defaults (timeouts, retries).
  • Events: Listen to Saloon\Events\RequestSent/ResponseReceived for cross-cutting concerns.
• HTTP Layer: Replaces manual Http::get() calls with typed connectors (e.g., StripeConnector::fetchUser()).
• Testing: Replaces Http::fake() with MockConnector for isolated tests.
• Queue System: Uses Laravel’s Bus for async requests (e.g., Saloon::queue()).

Migration Path

1. Phase 1: Pilot APIs
   • Migrate 1–2 high-complexity APIs (e.g., Stripe, GitHub) to Saloon connectors.
   • Replace raw Http calls with Connector::call() in services/controllers.
   • Example:

     // Before
     $user = Http::withToken($apiKey)->get('https://api.stripe.com/v1/users')->json();
     
     // After
     $user = app(StripeConnector::class)->fetchUser();
     

2. Phase 2: Standardize
   • Create a base SaloonService trait for Laravel services.
   • Enforce connector naming conventions (e.g., PascalCaseConnector).
   • Add Saloon middleware to app/Http/Kernel.php for global headers/auth.
3. Phase 3: Advanced Features
   • Implement retries/circuit breakers via Saloon’s decorators.
   • Add GraphQL/SOAP connectors for specialized APIs.
   • Integrate with Laravel Horizon for queue monitoring.

Compatibility

• Laravel Versions: Tested with Laravel 10+ (PHP 8.1+). Downgrade risks if using older versions.
• PHP Extensions: Requires curl, json, and mbstring (standard in Laravel).
• Third-Party Packages: Conflicts unlikely, but avoid mixing Saloon with other HTTP clients (e.g., guzzlehttp/guzzle) in the same project.
• Database: No direct dependency, but connectors may store cached responses in Laravel’s cache/database.

Sequencing

1. Setup:
   • Install via Composer: composer require saloonphp/laravel-plugin.
   • Publish config: php artisan vendor:publish --tag=saloon-config.
2. Connector Development:
   • Create connectors in app/Saloon/Connectors/ (or Modules/ if using Luminary).
   • Example:

     namespace App\Saloon\Connectors;
     
     use Saloon\Connector;
     use Saloon\Traits\Pluck;
     
     class StripeConnector extends Connector {
         use Pluck;
         protected string $baseUrl = 'https://api.stripe.com/v1';
         protected string $token = 'sk_live_...';
     }
     

3. Testing:
   • Mock connectors in tests:

     $this->mock(StripeConnector::class, [
         'fetchUser' => ['id' => 'user_123']
     ]);
     

4. Deployment:
   • Register connectors in AppServiceProvider:

     $this->app->bind(StripeConnector::class, fn() => new StripeConnector());
     

   • Add to config/saloon.php for global settings.

Operational Impact

Maintenance

• Pros:
  • Reduced Boilerplate: Connectors centralize API logic, reducing duplicate code.
  • Type Safety: Saloon’s return types (e.g., ConnectorResponse) integrate with Laravel’s IDE autocompletion.
  • Config-Driven: Global settings (timeouts, retries) managed in config/saloon.php.
• Cons:
  • Connector Bloat: Overly complex connectors may become hard to maintain. Mitigate with small, single-purpose connectors.
  • Dependency Updates: Saloon updates may require connector adjustments (e.g., new decorators).

Support

• Debugging:
  • Saloon’s debug() method logs requests/responses to Laravel’s log channel.
  • Use Saloon::extend() to add custom debug middleware.
• Error Handling:
  • Saloon throws SaloonHttpException; catch and map to Laravel’s HttpResponseException.
  • Example:

    try {
        $response = $connector->call();
    } catch (SaloonHttpException $e) {
        throw new HttpResponseException($e->getResponse());
    }
    

• Documentation:
  • Saloon’s official docs cover Laravel integration. Supplement with internal runbooks for custom connectors.

Scaling

• Performance:
  • Caching: Use Saloon’s cache() decorator or Laravel’s cache drivers to reduce API calls.
  • Queues: Offload long-running requests to Laravel’s queue system.
  • Load Testing: Monitor connector performance under load (e.g., with Laravel Forge/Envoyer).
• Horizontal Scaling:
  • Stateless connectors work well in multi-server Laravel deployments.
  • Shared cache (Redis) for connector responses if using distributed caching.
• Database Impact: Minimal, unless storing connector responses in DB (use Laravel’s cache instead).

Failure Modes