Relay Dispatch Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Modularity: The bundle follows a clear separation of concerns (API Gateway → Dispatch Bundle → Dual Delivery Service), aligning well with Laravel’s modular architecture. It integrates as a standalone Symfony bundle, requiring minimal core Laravel modifications.
• SOAP Integration: Specialized for DuaZSpec SOAP, which may limit flexibility if future APIs diverge from this spec. However, the bundle abstracts SOAP complexity, reducing boilerplate for TPMs.
• Event-Driven: CLI commands and status polling suggest an asynchronous workflow (e.g., dispatch → status fetch), which fits Laravel’s queue/background job ecosystem (e.g., Laravel Horizon).

Integration Feasibility

• Laravel Compatibility: Built for Symfony but leverages Doctrine ORM and Symfony components (e.g., HttpClient), which Laravel supports via symfony/http-client and doctrine/dbal. Potential friction:
  • Symfony’s DependencyInjection vs. Laravel’s Service Providers.
  • Symfony’s EventDispatcher vs. Laravel’s Events.
• Database: MySQL/MariaDB required; Laravel’s Eloquent can coexist if migrations are isolated (e.g., custom schema prefix).
• File Storage: Supports database blobs or external blob storage (e.g., S3). Laravel’s filesystem adapters (e.g., aws-sdk-php) can bridge gaps if using external storage.

Technical Risk

• SOAP Dependency: Hard dependency on DuaZSpec SOAP may require customization if the external service changes. Risk mitigation:
  • Abstract SOAP calls behind interfaces (e.g., DualDeliveryClientInterface) for mocking/testing.
  • Monitor for SOAP deprecation in the external service.
• Authorization Complexity: Group-based RBAC (ROLE_GROUP_WRITER, etc.) may clash with Laravel’s built-in auth (e.g., Gate, Policy). Risk:
  • Overhead to reconcile Symfony’s Voter system with Laravel’s auth.
  • Performance impact if groups scale (e.g., GROUPS attribute query on every request).
• CLI Tools: Heavy reliance on CLI for testing/status checks. Risk:
  • Limited visibility into async workflows without custom Laravel commands or queues.
  • Debugging may require hybrid CLI/Laravel debugging.

Key Questions

1. SOAP Flexibility:
   • Can the SOAP client be decoupled to support other protocols (REST/gRPC) if the external service evolves?
2. Auth Integration:
   • How will Laravel’s auth system (e.g., Sanctum, Passport) interact with the bundle’s RBAC? Will a custom Authenticator or middleware be needed?
3. Queue/Async Workflows:
   • Are the CLI commands (status-request, etc.) critical, or can they be replaced with Laravel queues (e.g., dispatch:status-poll)?
4. File Storage:
   • If using external blob storage (e.g., S3), how will Laravel’s filesystem stack integrate with the bundle’s blob_base_url config?
5. Testing:
   • Is there a mock SOAP server or test doubles for the DualDeliveryService to avoid hitting production endpoints in CI?
6. Performance:
   • How will the GROUPS attribute scale with many groups/users? Is caching (e.g., Laravel’s Cache facade) viable?

Integration Approach

Stack Fit

• Laravel Core: Compatible with Laravel 8+ (Symfony 5.4+ dependencies). Key overlaps:
  • Doctrine DBAL: Laravel’s Eloquent can coexist if migrations are namespaced (e.g., dbp_relay_dispatch_*).
  • Symfony HTTP Client: Replaceable with Laravel’s Http facade or Guzzle.
  • Events: Laravel’s event system can consume bundle events (e.g., DeliveryStatusChange) with minimal adapters.
• External Dependencies:
  • SOAP: Use php-soap (Laravel-compatible) or a modern alternative like ext-soap with a facade.
  • Blob Storage: Laravel’s Storage facade can wrap the bundle’s blob logic if using external storage.

Migration Path

1. Scaffold Integration:
   • Install via Composer: composer require dbp/relay-dispatch-bundle.
   • Publish config: php artisan vendor:publish --tag=dbp_relay_dispatch_config.
   • Configure config/packages/dbp_relay_dispatch.yaml with Laravel env vars (e.g., DATABASE_URL, SERVICE_URL).
2. Database:
   • Run migrations in a transaction or isolated schema:

     php artisan dbp:relay:dispatch:migrate --em=dbp_relay_dispatch_bundle
     

   • For Laravel’s Eloquent, create a custom connection or use a schema prefix.
3. Auth Bridge:
   • Extend Laravel’s AuthServiceProvider to map Symfony roles to Laravel gates/policies:

     // app/Providers/AuthServiceProvider.php
     public function boot(): void {
         Gate::define('ROLE_GROUP_WRITER', function (User $user, string $groupId) {
             return $this->bundleAuth->hasRole($user, 'ROLE_GROUP_WRITER', $groupId);
         });
     }
     

4. API Layer:
   • Expose bundle endpoints via Laravel routes:

     // routes/api.php
     Route::prefix('dispatch')->group(function () {
         \Symfony\Bundle\FrameworkBundle\Controller\AbstractController::class,
         'dispatch_bundle_controller',
         'index'
     });
     

   • Use Laravel middleware (e.g., auth:sanctum) to gate routes.
5. Async Workflows:
   • Replace CLI commands with Laravel queues:

     // app/Console/Commands/PollDeliveryStatus.php
     public function handle() {
         $dispatcher = app(DualDeliveryDispatcher::class);
         $dispatcher->pollStatuses();
     }
     

   • Dispatch via artisan or manually in code:

     PollDeliveryStatus::dispatch();
     

Compatibility

• Symfony vs. Laravel:
  • DependencyInjection: Use Laravel’s Container to bind Symfony services:

    $this->app->bind(DualDeliveryService::class, function ($app) {
        return new DualDeliveryService(
            $app['config']['dbp_relay_dispatch.service_url'],
            $app['http.client']
        );
    });
    

  • Events: Subscribe to bundle events in Laravel’s EventServiceProvider:

    protected $listen = [
        \Dbp\RelayDispatchBundle\Event\DeliveryStatusChangeEvent::class => [
            \App\Listeners\LogDeliveryStatus::class,
        ],
    ];
    

• Testing:
  • Mock SOAP calls with Laravel’s MockHttp or a test double:

    $this->mock(HttpClient::class)->shouldReceive('request')->andReturn(...);
    

Sequencing

1. Phase 1: Core Integration (2–3 weeks):
   • Install bundle, configure DB/auth, and expose basic API endpoints.
   • Validate SOAP communication with the external service.
2. Phase 2: Async Workflows (1–2 weeks):
   • Replace CLI commands with Laravel queues/jobs.
   • Implement status polling as a scheduled job (e.g., schedule:run).
3. Phase 3: Auth & RBAC (1 week):
   • Bridge Symfony roles to Laravel gates/policies.
   • Test group-based permissions.
4. Phase 4: File Storage (1 week):
   • Configure blob storage (database or external) and test file uploads.
5. Phase 5: Monitoring (1 week):
   • Add Laravel Scout/StatsD for tracking delivery statuses.
   • Implement health checks for SOAP connectivity.

Operational Impact

Maintenance

• Bundle Updates:
  • Monitor for breaking changes in the bundle’s CHANGELOG.md. Risk: SOAP spec updates may require bundle forks.
  • Dependency conflicts: Symfony 5.x vs. Laravel’s older Symfony components (e.g., http-foundation).
• Database:
  • Migrations must be run manually (no Laravel migrate integration). Risk of schema drift if not tracked.
  • Backup strategy needed for file_storage=database (blobs in DB tables).
• Configuration:
  • Sensitive data (e.g., cert, cert_password) must be managed via Laravel’s .env or secrets system.
  • Config validation: Add Laravel’s config:cache support for the bundle’s YAML.

Support

• Debugging:
  • Hybrid Symfony/Laravel stack may require familiarity with both ecosystems (e.g., Symfony’s DebugBundle vs. Laravel’s Tinker).
  • SOAP errors may surface as cryptic XML; log raw responses for debugging.
• Error Handling:
  • Custom error codes (e.g., dispatch:request-file-missing) should map to Laravel’s HttpException or a custom DispatchException.
  • Implement Sentry/Monolog for SOAP failures and auth rejections.
• Documentation:
  • Bundle