Speedy Pickup Point Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Laravel Compatibility:
  • Breaking Change: Dropped Symfony 6 support (now requires Symfony 7/8). Laravel integration remains feasible via HttpKernel or facade abstraction, but Symfony 8’s stricter typing may introduce edge cases (e.g., Attribute annotations, stricter PSR-15 middleware).
  • Domain Alignment: Unchanged—still ideal for Bulgarian logistics/e-commerce. No functional impact on Laravel use case.
• Modularity:
  • Command-based pattern (FindOffice, GetAllPostcodesRequest) remains Laravel-friendly, but Symfony 8’s dependency injection (DI) changes (e.g., Autowire improvements) may require adjustments to Laravel’s service binding.

Integration Feasibility

• Symfony 8 Dependency:
  • Risk: Laravel’s built-in Symfony components (e.g., HttpKernel) may lag behind Symfony 8. Requires explicit dependency:

    composer require symfony/http-kernel:^8.0 symfony/dependency-injection:^8.0
    

  • Workaround: Use a standalone Guzzle client (Option 2 from prior assessment) to avoid Symfony 8 entirely.
• Configuration Overhead:
  • Unchanged, but Symfony 8’s ContainerBuilder may complicate manual DI setup in Laravel.
• Guzzle HTTP Client:
  • No changes; Guzzle 7 remains compatible.

Technical Risk

Key Questions

1. Is Symfony 8 integration acceptable?
   • If not, abandon the bundle and build a Guzzle-based Laravel service (lower risk).
2. Will Laravel’s Symfony components support Symfony 8?
   • Check compatibility with symfony/http-kernel:^8.0 in Laravel’s ecosystem.
3. Are there Symfony 8-specific features we can leverage?
   • E.g., Attribute annotations for commands (if using facade abstraction).
4. Does the product need real-time updates?
   • Speedy.bg API latency remains a UX risk; caching is still critical.
5. Alternative logistics providers?
   • Vendor lock-in risk persists; evaluate fallback options.

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Option 1 (Symfony 8 Kernel): Deprecated due to risk. Replace with:

    // app/Providers/AppServiceProvider.php
    public function register()
    {
        $this->app->singleton('speedy.client', function () {
            return new \Answear\SpeedyBundle\Client(
                new \Answear\SpeedyBundle\Config\SpeedyConfig(
                    env('SPEEDY_USERNAME'),
                    env('SPEEDY_PASSWORD'),
                    env('SPEEDY_PRIVATE_KEY')
                )
            );
        });
    }
    

  • Option 2 (Recommended): Guzzle Standalone Client (avoids Symfony 8 entirely):

    // app/Services/SpeedyClient.php
    class SpeedyClient {
        public function __construct(private HttpClient $httpClient) {}
    
        public function findOffice(string $postcode): array {
            $response = $this->httpClient->post('https://api.speedy.bg/...', [
                'json' => ['postcode' => $postcode],
                'auth' => [env('SPEEDY_USERNAME'), env('SPEEDY_PASSWORD')],
            ]);
            return json_decode($response->getBody(), true);
        }
    }
    

• Dependencies:
  • New Requirement: symfony/http-client:^8.0 (if using Option 1) or guzzlehttp/guzzle:^7.0 (Option 2).

Migration Path

1. Phase 1: Evaluate Symfony 8 Risk
   • Test symfony/http-kernel:^8.0 in a staging environment with Laravel.
   • If unstable, proceed with Option 2 (Guzzle standalone).
2. Phase 2: Abstraction Layer
   • For Option 1, create a Laravel service to wrap Symfony 8’s Client:

     // app/Services/SpeedyService.php
     class SpeedyService {
         public function __construct(private ClientInterface $speedyClient) {}
     
         public function findOffice(string $postcode) {
             return $this->speedyClient->execute(new FindOfficeCommand($postcode));
         }
     }
     

   • For Option 2, implement the Guzzle client as shown above.
3. Phase 3: Configuration
   • Update .env for Symfony 8’s stricter config:

     SPEEDY_USERNAME=your_username
     SPEEDY_PASSWORD=your_password
     SPEEDY_PRIVATE_KEY=your_key
     SPEEDY_LANGUAGE=bg  # Symfony 8 enforces strict typing for enums
     

4. Phase 4: Testing
   • Mock Speedy.bg API using Laravel’s HttpClient mocking:

     $this->get(HttpClient::class)->shouldReceive('post')
         ->once()
         ->andReturn(new Response(200, [], json_encode(['offices' => [...]))));
     

Compatibility

• Laravel Versions:
  • Symfony 8 Support: Only Laravel 11+ (Symfony 7+) may work seamlessly. Laravel 10 will need manual patching.
  • PHP Version: Requires PHP 8.3+ (Symfony 8’s minimum).
• Database: Unchanged (no DB dependencies).
• Symfony 8-Specific:
  • PSR-15 Middleware: If using Symfony’s Client, ensure middleware (e.g., retries) are PSR-15 compliant.
  • Attributes: Symfony 8 uses PHP 8.0 Attribute for annotations (e.g., @Route). Laravel may require polyfills.

Sequencing

1. Install Dependencies:

   composer require guzzlehttp/guzzle:^7.0  # Option 2 (recommended)
   # OR
   composer require symfony/http-client:^8.0 symfony/dependency-injection:^8.0  # Option 1 (risky)
   

2. Implement Service Layer:
   • Choose Option 1 or 2 and implement the corresponding service.
3. Configure:
   • Update .env and bind the service in Laravel’s container.
4. Test:
   • Validate with mock API responses.
5. Deploy:
   • Monitor for Symfony 8/Laravel integration issues (e.g., DI errors).

Operational Impact

Maintenance

• Dependency Updates:
  • Critical: Symfony 8’s breaking changes (e.g., ContainerBuilder API, PSR-15) may require manual patches in Laravel.
  • Recommendation: Pin symfony/* dependencies to avoid auto-updates until Laravel fully supports Symfony 8.
• Logging:
  • Add Symfony 8-compatible logging (e.g., Monolog 3+):

    $logger = new \Symfony\Contracts\Service\ServiceSubscriberInterface();
    \Log::debug('Speedy API Call', ['data' => $request->getBody()]);
    

• Backward Compatibility:
  • Symfony 6 Code: If any legacy code uses Symfony 6, migrate to Symfony 8 or refactor to avoid the bundle.

Support

• Vendor Support:
  • No change: Still minimal community support. Rely on Speedy.bg’s API docs.
• Error Handling:
  • Symfony 8 Improvements: Better HTTP error handling (e.g., Problem details), but Laravel’s exception handler may need adjustments:

    catch (\Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface $e) {
        \Log::error('Speedy API Error', ['status' => $e->getResponse()->getStatusCode()]);
        throw new \RuntimeException('Logistics service unavailable.');
    }
    

• Rate Limiting:
  • Symfony 8’s HttpClient includes built-in retry logic. Configure in Laravel:

    $client = new \Symfony\Contracts\HttpClient\HttpClient(
        new \Sym