Przelewy24 Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony 3.3+ Focus: The bundle is tightly coupled to Symfony 3.x (last release in 2025, but no Symfony 4/5+ support). If migrating to Symfony 5/6/7, this could require significant refactoring or a fork.
• Event-Driven Design: Leverages Symfony’s event system (przelewy24.event.payment_success), which aligns well with modern Symfony architectures but may require custom event listeners for non-Symfony apps.
• Przelewy24 API Abstraction: Encapsulates Przelewy24’s payment flow (redirects, webhooks, sandbox testing), reducing boilerplate for payment integrations.
• Limited Laravel Compatibility: Designed for Symfony; Laravel’s service container, routing, and event systems differ significantly. Direct porting is non-trivial.

Integration Feasibility

• Core Features: Payment initiation, status callbacks, and sandbox testing are well-defined but require manual adaptation for Laravel’s ecosystem (e.g., routing, service binding).
• Guzzle Dependency: Uses Guzzle 6.x for HTTP requests, which Laravel already supports, but integration would need custom service wiring.
• Webhook Handling: Relies on Symfony’s event system; Laravel’s event system is similar but not identical (e.g., kernel.event_listener vs. Laravel’s listen()).
• Routing: Symfony’s routing.yml would need replacement with Laravel’s route definitions (e.g., Route::get()).

Technical Risk

• High Refactoring Effort: Not a drop-in solution for Laravel. Key risks:
  • Service Container: Symfony’s autowiring vs. Laravel’s IoC container.
  • Event System: Custom event listeners would need Laravel-compatible implementations.
  • Routing: Symfony’s XML routes vs. Laravel’s PHP-based routes.
  • Kernel Integration: AppKernel.php registration pattern doesn’t translate directly.
• Maintenance Burden: No active community (0 stars, 0 dependents). Last release in 2025 may lack long-term support.
• Testing Gaps: Sandbox tools are Symfony-specific; Laravel would need parallel test utilities.

Key Questions

1. Is Symfony 3.x a Hard Requirement? If the project is Laravel-only, assess whether a Symfony micro-framework (e.g., Symfony Components) or a native Laravel package (e.g., przelewy24-laravel) is preferable.
2. Event System Compatibility How will przelewy24.event.payment_success be mapped to Laravel’s events? Would a custom event dispatcher bridge be needed?
3. Webhook Security Przelewy24’s status callbacks require secure endpoint handling. How will Laravel’s middleware/validation integrate with the bundle’s ProcessFactory?
4. Routing Strategy Can Symfony’s XML routes be converted to Laravel’s Route::match() or would a custom controller adapter be required?
5. Sandbox Testing The /p24-test and /p24-fake-success endpoints are dev-only. How will these be replicated in Laravel’s testing environment?
6. Custom Merchant Support The v1.2.0 feature allows dynamic merchant IDs. Is this critical, or can hardcoded values suffice for Laravel?
7. Error Handling The bundle’s exception handling (e.g., verifyadapter fixes in v1.1.1) may need Laravel-specific overrides.

Integration Approach

Stack Fit

• Laravel vs. Symfony: The bundle is not natively compatible with Laravel. A TPM must decide between:
  • Option 1: Fork and Adapt Rewrite key components (routing, events, services) to use Laravel’s ecosystem. High effort but future-proof.
  • Option 2: Hybrid Integration Use the bundle’s core logic (e.g., ProcessFactory, Payment model) via a Laravel service while adapting Symfony-specific parts (e.g., events → Laravel events).
  • Option 3: Abandon Bundle Build a lightweight Laravel package using Przelewy24’s API directly (e.g., Guzzle + custom controllers).
• Dependencies:
  • Guzzle 6.x: Already supported by Laravel.
  • Symfony Components: If using Option 1/2, may require symfony/http-client, symfony/event-dispatcher, etc.

Migration Path

1. Phase 1: Proof of Concept
   • Extract the bundle’s core logic (ProcessFactory, Payment model) into a Laravel-compatible service.
   • Test payment initiation (redirect flow) without events/webhooks.
2. Phase 2: Event System Bridge
   • Map Symfony events (PaymentEventInterface) to Laravel events (e.g., PaymentSucceeded).
   • Implement a custom event dispatcher or use Laravel’s Event facade.
3. Phase 3: Webhook Handling
   • Replace Symfony’s routing.xml with Laravel routes for status callbacks.
   • Add middleware for CRC validation (Przelewy24’s security check).
4. Phase 4: Testing Utilities
   • Replicate /p24-test and /p24-fake-success as Laravel routes with similar functionality.
5. Phase 5: Deployment
   • Configure Laravel’s service container to bind ProcessFactory and related classes.
   • Update config/services.php (Laravel’s equivalent of services.yml).

Compatibility

Sequencing

1. Core Logic Extraction
   • Isolate ProcessFactory and Payment into a Laravel service.
   • Example:

     // app/Services/Przelewy24Service.php
     class Przelewy24Service {
         public function createPaymentUrl(Payment $payment, string $merchantId, string $crcKey): string {
             // Reimplement ProcessFactory::createAndGetUrl()
         }
     }
     

2. Event System Setup
   • Define Laravel events:

     // app/Events/PaymentSucceeded.php
     class PaymentSucceeded implements ShouldBroadcast {
         public function __construct(public string $sessionId) {}
     }
     

   • Listen for Przelewy24 callbacks and dispatch events.
3. Routing Layer
   • Replace Symfony routes with Laravel routes:

     Route::post('/przelewy24/callback', [Przelewy24Controller::class, 'handleCallback']);
     

4. Testing Infrastructure
   • Add Laravel routes for sandbox testing:

     Route::get('/p24-test', [Przelewy24TestController::class, 'testConnection']);
     Route::get('/p24-fake-success/{sessionId}', [Przelewy24TestController::class, 'simulateSuccess']);
     

5. Integration Testing
   • Test payment flow in Laravel’s testing environment (Pest/PHPUnit).
   • Verify webhook signatures and event dispatching.

Operational Impact

Maintenance

• Short-Term:
  • High initial effort due to Symfony-Laravel divergence. Expect 2–4 weeks for a full adaptation.
  • Custom event listeners and middleware may require ongoing tweaks.
• Long-Term:
  • Dependency Risk: Bundle’s lack of activity (0 stars, no dependents) may lead to unpatched vulnerabilities.
  • Laravel Updates: Future Laravel versions may break compatibility if using Symfony components.
  • Fork Strategy: If maintaining a fork, ensure CI/CD pipelines test both Symfony and Laravel branches.

Support

• Community:
  • No active maintainer or community (0 stars, 0 issues). Support will rely on:
    • Symfony documentation (for original bundle).
    • Laravel forums for adaptation challenges.
• Vendor Lock-in:
  • Przelewy24’s API changes may require updates to the bundle. A custom Laravel package reduces lock-in.
• Debugging:
  • Symfony-specific logs (e.g., AppKernel) won’t translate directly. Custom logging (Laravel’s Log facade) will be needed.

Scaling

• Performance:
  • The bundle’s Guzzle-based HTTP calls should scale well, but:
    • Symfony’s event system may add overhead. Laravel’s events are similarly lightweight.
    • Webhook callbacks must handle high concurrency (e.g., rate-limiting middleware).