With PPI-1056, the PayPal extension has undergone one of its most significant internal refactors to date. This release is not just about modernizing the codebase — it’s about creating a sustainable foundation for future development. The rework introduces a unified payment flow, removes legacy components, and aligns the extension with Shopware 6.7’s updated payment architecture.
For developers building custom integrations, maintaining extensions, or contributing to Shopware’s ecosystem, this release brings meaningful improvements in clarity, testability, and extensibility.
Out with the Old, In with the Abstract
At the center of this refactor is the replacement of the now-deprecated PayPalHandler.php. Previously responsible for the PayPal payment method, this class had become a bottleneck for maintainability. Its monolithic design, tightly coupled dependencies, and duplicated logic made it difficult to extend and even harder to test.
The new foundation is built around AbstractPaymentMethodHandler.php, a dedicated base class for all payment methods. This class consolidates core functionality — including the pay(), finalize(), and executeOrder() methods — into a single, centralized location. It also standardizes token handling and service injection patterns across the extension. Handlers like PayPalPaymentHandler.php now inherit from this abstract class, focusing solely on method-specific behavior. This change significantly reduces code duplication and ensures that all payment flows follow a consistent, predictable structure. The result is an extension architecture that is easier to understand, safer to extend, and better prepared to evolve alongside Shopware itself.
Cleaning Up After Ourselves
A previous refactor, PPI-1055 - Remove PayPal Plus, involved the removal of deprecated builders, patch classes, and outdated test mocks. PayPal has deprecated their PayPal PLUS service in favor of the PayPal Commerce Platform, which offers more payment options including wallets like Apple Pay and Google Pay. This meant the related PayPal PLUS code had become redundant. In the latest iteration, components like AbstractPaymentBuilder.php, various patch builders, and legacy mock repositories have all been removed. This cleanup is more than cosmetic. By reducing technical debt, it improves the extension’s performance and stability while lowering the cognitive load for contributors. Developers exploring or contributing to the extension will encounter less friction and clearer boundaries between responsibilities.
Welcome to the 6.7 Era
Perhaps the most strategic aspect of this refactor is its alignment with the direction Shopware is taking in version 6.7 and beyond. The new architecture moves away from the older AsynchronousPaymentHandlerInterface and SynchronousPaymentHandlerInterface, favoring an abstract base class structure that cleanly separates responsibilities.
Core methods like pay() and finalize() are now structured as internal flow steps, with executeOrder() acting as the primary override point for custom logic. This aligns SwagPayPal with Shopware’s standardized lifecycle and improves support for recurring payments, vaulting, and wallet integrations.
For developers, this means better compatibility with the platform’s evolving standards, and more predictable behavior when working across different payment methods.
What to Expect if You’ve Extended SwagPayPal
If you’ve built custom payment handlers or extensions that extended any payment Handler.php or used now-removed components like the V1 builders, you’ll need to migrate your code. Adopting AbstractPaymentMethodHandler.php as your new base is a required step moving forward.
Although this is a breaking change for some use cases, the migration path is clear — and the benefits are tangible. The new structure improves clarity, reduces boilerplate, and ensures long-term compatibility with Shopware’s payment ecosystem.
What This Means for the Community
This refactor is more than just a facelift. It’s an invitation. Let’s build smarter payment flows, with less effort and more confidence. It encourages contribution by making the extension more approachable. And it ensures that as Shopware evolves — whether it's adding new wallet types, introducing regulatory features, or integrating with third-party systems — the foundation is solid and ready. Happy contributing.
