Netopia Mobilpay Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Laravel vs. Symfony Misalignment: The bundle is Symfony-centric, relying on Symfony’s dependency injection, configuration system, and HTTP components. Laravel’s service container, facades, and Eloquent ORM introduce architectural friction when adapting this bundle. The TPM must decide whether to:
  • Fully port the bundle to Laravel (high effort, ongoing maintenance).
  • Use as a reference and rebuild core logic in Laravel-native components (lower risk, but reinvents some wheel).
  • Abstract via a middleware layer (e.g., Omnipay) to decouple from Symfony specifics.
• Payment Gateway Patterns: The bundle follows a transactional gateway pattern (initiate payment → redirect → webhook callback), which is Laravel-compatible but requires customization for Laravel’s routing, middleware, and queue systems.
• State Management: Symfony’s event system (e.g., kernel.request) may need replacement with Laravel’s events or observers, adding complexity.

Integration Feasibility

• High-Level Feasibility:
  • API Integration: MobilPay’s API is REST-based and stateless, making it adaptable to Laravel’s HTTP clients (Guzzle, Symfony HttpClient, or Laravel’s built-in HTTP).
  • Configuration: Symfony’s YAML/config system can be mapped to Laravel’s .env + config/services.php with minimal effort.
  • Webhooks: Laravel’s middleware pipeline and queues can handle MobilPay’s asynchronous callbacks, but signature validation logic must be ported.
• Low-Level Challenges:
  • Symfony-Specific Abstractions:
    • ContainerAware services → Laravel’s dependency injection (via constructors or bind()).
    • HttpFoundation\Request → Laravel’s Illuminate\Http\Request.
    • EventDispatcher → Laravel’s Event facade.
  • Certificate/Key Handling: The bundle supports file paths or string content for certificates/keys. Laravel’s Storage or Filesystem can replace Symfony’s file handling.
  • No Laravel SDK: Unlike Stripe or PayPal, MobilPay lacks a Laravel package, forcing custom implementation of core logic (e.g., request signing, response parsing).

Technical Risk

Key Questions for the TPM

1. Strategic Fit:
   • Is MobilPay a primary or secondary payment method? If secondary, consider a multi-gateway abstraction (e.g., Omnipay) to reduce custom work.
   • Does the team have Laravel payment gateway experience? If not, budget for knowledge transfer or hire a specialist.
2. Architectural Tradeoffs:
   • Should the TPM fully port the bundle (high effort) or rebuild core logic in Laravel (lower risk, but reinvents some wheel)?
   • Will the project benefit from long-term maintainability of a Laravel-native package, or is a quick-and-dirty integration sufficient?
3. Security and Compliance:
   • How will private keys/certificates be stored? Options: Laravel Vault, encrypted .env, or AWS Secrets Manager.
   • Are there audit requirements for payment logs? If yes, customize Laravel’s Log or use a dedicated solution (e.g., Sentry, Datadog).
4. Webhook Reliability:
   • How will MobilPay’s asynchronous notifications (e.g., payment confirmations) be handled? Options:
     • Laravel Queues (with retries for failed jobs).
     • Direct HTTP callbacks (with middleware validation).
   • What’s the SLA for webhook retries? Design accordingly (e.g., exponential backoff).
5. Performance:
   • Will the integration support high-volume transactions? If yes, optimize:
     • Caching of certificate/key files (avoid repeated file reads).
     • Queue batching for webhook processing.
6. Monitoring:
   • How will payment failures be monitored? Options:
     • Laravel Horizon (for queue monitoring).
     • Custom metrics (e.g., failed signatures, timeout errors).
     • Third-party tools (e.g., Sentry, Datadog).

Integration Approach

Stack Fit

• Laravel Compatibility:
  • ✅ Core Logic: Payment API calls, request signing, and response parsing are framework-agnostic and can be adapted to Laravel.
  • ⚠️ Symfony-Specific Features:
    • Dependency injection, events, and HTTP components require rewrites.
    • Configuration system (YAML → .env + config/services.php).
  • ❌ Poor Fit:
    • Symfony’s ContainerAware services (replace with Laravel’s DI).
    • Event system (replace with Laravel’s Event facade or observers).
• Recommended Stack:
  • Laravel 9+ (PHP 8.1+) for modern features (e.g., enums, attributes).
  • Guzzle HTTP Client (or Laravel’s built-in HTTP client) for API calls.
  • Laravel Queues for asynchronous webhook processing.
  • Laravel Cashier (if MobilPay supports subscriptions) or Omnipay (for multi-gateway support).
  • Laravel Vault or encrypted .env for sensitive keys.

Migration Path

Phase 1: Dependency Extraction (2–3 Weeks)

• Goal: Remove Symfony-specific code; abstract to Laravel-compatible components.
• Tasks:
  1. Fork the bundle and strip Symfony dependencies:
     • Replace Symfony\Component\HttpFoundation\Request → Illuminate\Http\Request.
     • Replace Symfony\Component\DependencyInjection → Laravel’s bind() or AppServiceProvider.
     • Replace Symfony\Component\EventDispatcher → Laravel’s Event facade.
  2. Abstract configuration:
     • Map config/packages/netopia_mobilpay.yaml to .env and config/services.php.
     • Example .env:

       NETOPIA_MOBILPAY_PAYMENT_URL=https://api.mobilpay.ro
       NETOPIA_MOBILPAY_PUBLIC_CERT=file://path/to/cert.pem
       NETOPIA_MOBILPAY_PRIVATE_KEY=file://path/to/key.pem
       NETOPIA_MOBILPAY_SIGNATURE=your_signature_key
       

  3. Replace Symfony’s HttpClient with Guzzle or Laravel’s HTTP client.

Phase 2: Service Wrapper (1–2 Weeks)

• Goal: Create a Laravel-native service class to encapsulate MobilPay logic.
• Implementation:
  1. Create app/Services/MobilPayService.php:

     namespace App\Services;
     
     use Illuminate\Support\Facades\Http;
     use Illuminate\Support\Facades\Log;
     use Illuminate\Support\Facades\Storage;
     
     class MobilPayService
     {
         public function createPayment(array $data): array
         {
             $response = Http::withHeaders([
                 'Content-Type' => 'application/json',
             ])->post(config('services.mobilpay.payment_url'), $data);
     
             return $response->json();
         }
     
         public function verifySignature(array $data): bool
         {
             // Port the bundle's signature verification logic here
             $expectedSignature = hash_hmac(
                 'sha256',
                 $data['payload'],
                 config('services.mobilpay.signature')
             );
             return hash_equals($expectedSignature, $data['signature']);
         }
     }
     

  2. Register the service in AppServiceProvider:

     public function register()
     {
         $this->app->singleton(MobilPayService::class, function ($app) {
             return new MobilPayService();
         });
     }
     

  3. Create a facade for cleaner usage:

     // app/Facades/MobilPay.php
     namespace App\Facades;
     
     use Illuminate\Support\Facades\Facade;
     
     class MobilPay extends Facade