Delivery Laravel Package

Technical Evaluation

Architecture Fit

• Modularity: The package (baks-dev/delivery) remains a Symfony bundle, but the new release (v7.4.5) introduces explicit Laravel compatibility notes in the documentation, suggesting the authors are acknowledging the integration gap. This reduces the need for custom abstraction layers but still requires service provider binding and Doctrine-Eloquent reconciliation.
• Domain-Specific: Continues to focus on order delivery workflows, but the new release adds webhook support for delivery events (e.g., transport_assigned, delivery_failed). This aligns well with Laravel’s event system and queue workers, enabling seamless integration for async processing (e.g., notifying third-party logistics providers).
• Event-Driven Potential: The new release formalizes event emission (e.g., DeliveryEvent::TRANSPORT_ASSIGNED). These can be mapped to Laravel’s Event facade or queued jobs for scalability. The package now includes a DeliveryEventDispatcher trait, simplifying event integration.

Integration Feasibility

• PHP 8.4+ Requirement: Unchanged. Laravel 11+ (PHP 8.3+) may still require runtime adjustments or a custom Docker image for full compatibility. Risk remains low if using Laravel 11+ with PHP 8.4.
• Doctrine ORM Dependency: The new release introduces a DeliveryRepositoryInterface with optional Eloquent adapter support, reducing conflict risk. Mitigation strategies updated:
  • Option 1 (Recommended): Use the Eloquent adapter (if provided) or a hybrid repository (e.g., spatie/laravel-doctrine-orm).
  • Option 2: Treat as a read-only service via API (new DeliveryClient class in v7.4.5).
• Symfony vs. Laravel: The release adds a LaravelServiceProvider stub in the docs, suggesting the authors expect Laravel users to extend it. This reduces DI complexity but still requires custom binding for Symfony-specific components (e.g., Console).

Technical Risk

Key Questions

1. Business Criticality:
   • Updated: With webhook support, is the package now a critical extension (e.g., for real-time logistics APIs) or still auxiliary?
2. Data Ownership:
   • Updated: Does the new DeliveryRepositoryInterface support shared schema (Laravel migrations) or require Doctrine ownership?
3. Extensibility Needs:
   • Updated: Can custom transport types be added via Laravel’s service binding (e.g., DeliveryTransport::extend())?
4. Performance:
   • New: Benchmark webhook event processing (e.g., DeliveryEvent::dispatch() vs. Laravel’s event()).
5. Long-Term Maintenance:
   • Updated: Is baks-dev/core actively maintained? Check if v7.4.5 includes backward-compatibility guarantees for Laravel.

Integration Approach

Stack Fit

• Laravel Compatibility:
  • New: LaravelServiceProvider stub reduces DI complexity. Use service binding for:

    // app/Providers/BaksDeliveryServiceProvider.php
    public function register()
    {
        $this->app->singleton(DeliveryManager::class, function ($app) {
            return new DeliveryManager(
                $app->make(DeliveryRepositoryInterface::class), // Eloquent adapter
                $app['events']
            );
        });
    }
    

  • Webhooks: Leverage Laravel’s Http\Client or queue:work for async processing.
  • Events: Map Symfony events to Laravel’s Event::dispatch():

    // Listen to transport assignment
    event(new TransportAssigned($orderId));
    

• Recommended Architecture:

  Laravel App
  ├── Service Layer (Adapters for baks-dev/delivery)
  │   ├── DeliveryService (Facade)
  │   ├── TransportRepository (Eloquent Adapter)
  │   ├── WebhookListener (Laravel Event Listener)
  ├── Console (Artisan Commands)
  │   ├── BaksAssetsInstallCommand (Wrapper)
  ├── Events
  │   ├── DeliveryEventServiceProvider (Maps Symfony events)
  ├── Http (Webhook Endpoints)
  │   ├── DeliveryWebhookController
  

Migration Path

1. Phase 1: Proof of Concept (2 weeks)

   • Install baks-dev/delivery:^7.4.5 and test core workflows (e.g., transport assignment).
   • Verify Eloquent adapter works or implement a hybrid repository.
   • Test webhook emission (e.g., DeliveryEvent::TRANSPORT_ASSIGNED).

2. Phase 2: Abstraction Layer (3 weeks)

   • Extend LaravelServiceProvider stub to bind Symfony services.
   • Create a facade (Delivery::assignTransport()) and event listeners.
   • Example:

     // app/Providers/EventServiceProvider.php
     protected $listen = [
         'baks.delivery.transport_assigned' => [
             DeliveryAssignedListener::class,
         ],
     ];
     

3. Phase 3: Full Integration (4 weeks)

   • Replace Laravel’s delivery logic with the package’s features.
   • Implement webhook endpoints (e.g., /api/delivery/webhook) using Laravel’s Route::post().
   • Write integration tests for:
     • Event emission → Laravel queue processing.
     • Webhook payload validation.

Compatibility

Sequencing

1. Prerequisites:
   • Upgrade Laravel to PHP 8.4+ (or containerize).
   • Install doctrine/dbal and symfony/console if missing.
2. Core Integration:
   • Bind Symfony services → Laravel container using LaravelServiceProvider.
   • Resolve Doctrine migrations via Eloquent adapter or DBAL.
3. Feature Adoption:
   • Replace Laravel’s delivery logic with the package’s transport assignment and event system.
   • Implement webhook endpoints for async processing.
4. Testing:
   • Unit tests for adapter layer (e.g., DeliveryRepository).
   • Integration tests for event → queue → webhook flow.
5. Deployment:
   • Run php artisan vendor:publish --provider="BaksDeliveryServiceProvider".
   • Apply migrations (doctrine:migrations:migrate via DBAL or Laravel’s migrate).

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor baks-dev/delivery for breaking changes in event names or webhook schemas.
  • Risk: Webhook contracts may change; document versioned endpoints.
• Configuration Management:
  • Publish configs/assets via Laravel’s vendor:publish.
  • Example config/delivery.php:

    return [
        'webhooks' => [
            'enabled' => env('DELIVERY_WEBHOOKS_ENABLED', true),
            'queue' => 'delivery_webhooks',
        ],
    ];
    

• Logging:
  • Redirect Symfony logs to Laravel’s monolog using a log channel adapter:

    // app/Providers/AppServiceProvider.php