Payment Laravel Package

Technical Evaluation

Architecture Fit

• Modular & Decoupled: The package follows a component-based architecture, aligning well with modern PHP/Laravel applications that prioritize separation of concerns (e.g., payment logic isolated from order/business logic).
• Domain-Driven Design (DDD): Leverages entities (e.g., Payment, PaymentMethod) and value objects, which integrates cleanly with Laravel’s Eloquent ORM and DDD-friendly frameworks like Laravel Scout or Spatie’s DDD packages.
• Event-Driven: Supports payment events (e.g., PaymentCompleted, PaymentFailed), enabling seamless integration with Laravel’s event system or queue workers (e.g., laravel-queue).
• Gateway Agnostic: Designed to work with any payment processor (via adapters), reducing vendor lock-in. Defaults to Payum (a robust payment abstraction library), but can integrate with Stripe, PayPal, or custom gateways via Laravel’s service providers.

Integration Feasibility

• Laravel Compatibility:
  • Eloquent Models: Payment entities (Payment, PaymentMethod) can be mapped to Laravel’s Eloquent models with minimal effort (e.g., using hasMany, belongsTo relations).
  • Service Container: Designed for dependency injection, fitting Laravel’s IoC container natively.
  • Middleware: Supports payment-specific middleware (e.g., auth checks, rate limiting) via Laravel’s middleware pipeline.
• Database Schema:
  • Migrations: The package provides Doctrine migrations, but Laravel’s migration system can adapt them with minor adjustments (e.g., Schema::create vs. Doctrine’s Migration).
  • Soft Deletes: Compatible with Laravel’s SoftDeletes trait for payment records.
• API-First: Built for REST/GraphQL APIs, aligning with Laravel’s API resources and Fractal/Spatie’s API tools.

Technical Risk

• Learning Curve:
  • Sylius Ecosystem: If the team is unfamiliar with Sylius components, ramp-up time may increase (though Laravel’s familiarity mitigates this).
  • Payum Dependency: Defaults to Payum, which adds another abstraction layer. If the team prefers direct gateway SDKs (e.g., Stripe PHP), this may require custom adapter development.
• State Management:
  • Payments are stateful (e.g., pending, completed, failed), requiring careful handling of transactions and retries. Laravel’s database transactions and queue jobs can manage this, but edge cases (e.g., partial refunds) may need custom logic.
• Testing Complexity:
  • Mocking Gateways: Unit/integration tests will need mock payment gateways (e.g., using Laravel’s Mockery or PHPUnit).
  • Event-Driven Flow: Testing asynchronous events (e.g., webhooks) may require Laravel’s Testing facade or PestPHP for complex scenarios.

Key Questions

1. Gateway Strategy:
   • Will the team use Payum (default) or direct SDKs (e.g., Stripe, PayPal)? If the latter, how will adapters be built?
2. State Transitions:
   • Are there custom payment states beyond the default (e.g., refunded, disputed)? How will these be modeled?
3. Idempotency:
   • How will duplicate payments (e.g., retried webhooks) be handled? Laravel’s idempotency middleware or custom logic?
4. Webhooks:
   • Will external payment providers send webhooks? If so, how will Laravel’s route model binding or queue listeners process them?
5. Multi-Currency/Support:
   • Does the system require multi-currency payments? The package supports this, but Laravel’s localization (e.g., setlocale) and database collations must align.
6. Compliance:
   • Are there PCI DSS or regulatory requirements (e.g., GDPR for payment data)? How will Laravel’s encryption (e.g., laravel-encryption) or third-party vaults (e.g., HashiCorp Vault) integrate?

Integration Approach

Stack Fit

• Laravel Core:
  • Eloquent: Direct mapping of Payment, PaymentMethod entities to Laravel models.
  • Service Container: Register components via config/app.php or a custom service provider.
  • Middleware: Add payment-specific middleware (e.g., EnsurePaymentMethodExists) to routes.
• Laravel Ecosystem:
  • Queues: Offload payment processing to Laravel Queues (e.g., PaymentProcessorJob).
  • Events: Dispatch custom events (e.g., PaymentProcessed) for notifications or analytics.
  • API Tools: Use Laravel API Resources to shape payment responses for REST/GraphQL.
• Third-Party Gateways:
  • Payum: If adopted, integrate via payum/payum and configure adapters for Stripe/PayPal.
  • Direct SDKs: Build custom Laravel service classes to wrap gateway SDKs (e.g., StripeService).

Migration Path

1. Scaffold Models:
   • Convert Sylius payment entities to Laravel Eloquent models:

     // app/Models/Payment.php
     class Payment extends Model {
         use SoftDeletes;
         protected $fillable = ['amount', 'state', 'method_id', 'order_id'];
     }
     

2. Database Setup:
   • Adapt Sylius migrations to Laravel’s Schema::create or use Doctrine migrations via laravel-doctrine/orm.
   • Example:

     Schema::create('payments', function (Blueprint $table) {
         $table->id();
         $table->foreignId('order_id')->constrained();
         $table->string('amount')->nullable();
         $table->string('state'); // e.g., 'pending', 'completed'
         $table->foreignId('method_id')->constrained('payment_methods');
         $table->timestamps();
         $table->softDeletes();
     });
     

3. Service Layer:
   • Create a PaymentService to orchestrate logic:

     class PaymentService {
         public function process(Payment $payment, PaymentMethod $method) {
             event(new PaymentProcessing($payment));
             // Delegate to gateway via Payum or direct SDK
         }
     }
     

4. Gateway Integration:
   • Option A (Payum):
     • Install payum/payum and configure adapters in config/payum.php.
     • Example Payum config:

       'stripe' => [
           'factory' => 'stripe',
           'api_key' => env('STRIPE_SECRET'),
       ],
       

   • Option B (Direct SDK):
     • Wrap Stripe/PayPal SDKs in Laravel services:

       class StripeGateway {
           public function createPaymentIntent(float $amount): array {
               return \Stripe\PaymentIntent::create(['amount' => $amount * 100]);
           }
       }
       

5. Event Listeners:
   • Listen for payment events and trigger actions (e.g., send receipts):

     PaymentProcessed::class => [EmailService::class, 'sendReceipt'],
     

Compatibility

• Laravel Versions:
  • Tested with Laravel 9+ (PHP 8.0+). Ensure compatibility with your Laravel version (e.g., Eloquent changes in Laravel 10).
• PHP Extensions:
  • Requires pdo, bcmath (for currency calculations). No major conflicts with Laravel’s defaults.
• Sylius-Specific:
  • Avoid Sylius-specific traits (e.g., Sylius\Component\Core\Model\AdjustableInterface). Use Laravel’s alternatives (e.g., HasAdjustments trait).

Sequencing

1. Phase 1: Core Integration
   • Models, migrations, and basic service layer.
   • Goal: Support CRUD for payments/methods.
2. Phase 2: Gateway Integration
   • Choose Payum or direct SDKs. Implement one primary gateway first (e.g., Stripe).
   • Goal: Process payments end-to-end.
3. Phase 3: Advanced Features
   • Webhooks, refunds, subscriptions (if needed).
   • Goal: Full payment lifecycle support.
4. Phase 4: Testing & Optimization
   • Load testing (e.g., Laravel Dusk or PestPHP).
   • Goal: Ensure scalability and reliability.

Operational Impact

Maintenance

• Dependency Management:
  • Payum: Adds a third-party dependency with its own updates. Monitor payum/payum for breaking changes.
  • Gateways: SDKs