Payum 2.0 Roadmap

[pierredup]

Work on Payum 2.0 is going strong, and there are a few open discussion points that I would like to address here.

Firstly, here is a high-level roadmap of what can be expected in Payum 2.0:

Roadmap

• PHP 8.0 (or 8.1) minimum (4f3f6e0)
• Add strict types internally wherever possible without breaking any changes (more on this below)
• Support for PSR18 clients using php-http (Replace HttpClient with PSR-18 HTTP Client #975)
• Configuration objects for gateways, moving away from array configuration
• Helper methods to make it easier to initiate and capture a payment (Add helper actions to easier execute common actions #969)
• Symfony 5, 6 and 7 support
• Updated integration with Laravel, Yii, Laminas etc.
• Remove old and deprecated library support
  • Propel (Remove Propel #938)
  • Zend (Remove Zend #974)
• Better way to register actions and api's
• Remove some Actions and use global helpers instead (E.G GetCurrencyAction can be deprecated as it does not serve a real purpose. Just use Currency::createFrom...) instead)
• Integration with moneyphp
• Native integration with ApiPlatform for headless payments
• Dependency Injection Container for config options (Moving away from the ArrayObject for gateway configs) (Add Dependency Injection integration #996)
• Up to date payment gateways integration (I.E remove old deprecated gateways and replace with up to date integration).
• Add more default functionality in core that's only available in framework integration (E.G events, logging etc)
• More?....

Breaking changes

One thing that I'm considering is to have zero breaking changes in version 2.0.

The reason for this is because there are hundreds of custom payment gateways built on Payum, and I want those to continue working with 2.0 so that there are no changes needed to continue using them. Especially for some applications that offer integration with a lot of different gateways, they will lose those integration if we don't continue to support the old API.

Some of the external payment gateways might not be maintained and be able to upgrade to Payum 2.0, but they might still work perfectly fine (and not need any additional maintenance).

For this reason, I'm thinking of keeping BC 100% between version 1 and 2, and adding deprecations somewhere in version 2 (which can then be removed in version 3).

Gateways in core

Payum core offers a few built-in gateways as part of the monorepo.

I think these should be moved out to separate packages away from the monorepo, and managed as independent packages and integrations (which can still be maintained by the Payum core team for the foreseeable future). Then the focus on the Payum repository can be on the Core functionality only.

Timeline

There is no definitive timeline on when Payum 2 will be released, as there are a lot of work involved in getting everything ready. I encourage the community to help contribute some of these changes to get to the endpoint quicker and have Payum 2 ready as soon as possible.

[pierredup]

Some feedback from @rimas-kudelis on #975 about the BC breaks:

@rimas-kudelis:

Hmm, not sure I'm a fan of the idea. It's not often that you're releasing a new major version. IMO, cleaning up as much as possible while doing so would make sense, unless Payum were willing to commit to some soft of a predictable major release schedule (like Symfony and PHP itself).

@pierredup:

There are hundreds of custom gateways available that might not all get updated to support V2, so releasing a new major version with no compatible gateways (except the built-in ones) and having slow adoption does not sound like a good strategy. I want people to be able to upgrade to Payum V2 and get access to some of the new features and cleaner code, without having to wait for their gateways to get updated, otherwise most people will just stay on V1

It's not often that you're releasing a new major version. IMO, cleaning up as much as possible while doing so would make sense

Just because a new major version is released, doesn't mean you need to take that chance and break as much as possible for everyone. A lot of clean up can still happen while still keeping existing functionality and gateways working.

It does not make sense for me to release a new major version that would hardly be usable in most applications without a lot of extra effort, or not being able to use any existing payment gateways because the author doesn't update it soon enough

@rimas-kudelis:

I get your point. I guess, as a fan of semver, I just have that habit of associating major releases with API breakage and not seeing it as a bad thing.

But if you intend to keep the old API intact, I just don't see much of a point to call this next release 2.0, I guess, because I see it more as an incremental change (1.x) than something big.

Of course, I don't know what else is changing and how, but assuming that your intention is to keep the work required to migrate at zero, it still seems like a minor release to me. :)

On the other hand, you yourself said in #954:

I think it makes sense to remove any HTTP client integration in Payum core, since I don't think it's needed or used anywhere inside core, and let each gateway do it's own HTTP client integration.

and I agree with this quote wholeheartedly. I think that not providing its own HTTP client could potentially make Payum a bit easier to work with and a bit cleaner code-wise. It would allow to drop some classes and interfaces entirely, and clean up at least one other place (CoreGatewayFactory), making it more maintainable.

@pierredup:

as a fan of semver, I just have that habit of associating major releases with API breakage and not seeing it as a bad thing

According to Semver, when releasing a new major version, you CAN break BC, not that you MUST break BC.
Releasing a new major version without any breakages still conforms perfectly to semver.

But if you intend to keep the old API intact, I just don't see much of a point to call this next release 2.0, I guess, because I see it more as an incremental change (1.x) than something big.

There are a lot of changes planned for 2.0, so I want to release it as a new major version with a lot of overhaul and new features, which warrants a new major version. Nobody will be excited about a 1.8 release :)

On the other hand, you yourself said in #954:

And I still stand with this 100%, just not for the next release. The migration path to 2.0 should be as smooth as possible, then we can start working on more breaking changes for 3.0.

[rimas-kudelis]

Some more feedback from myself:

• PHP 8.0 will be out of official support in four days, so I think 8.1 should be safe to require, assuming you're willing to use at least some of its new features.
• Meanwhile, Symfony 5.4 remains in active maintenance until late 2024, and then in security support until late 2025, so I think it would be a bit premature to drop support for it so early. Is there a good enough justification to do that? The 6.4 LTS release will only come out in a couple days. At least Sylius, through which I came to know of Payum, still supports 5.4, and I assume it will stay that way for a while, so I think you should also reconsider. Unless of course Payum v2 is nowhere around the corner yet. 😁
• +1 on extracting all integrations into separate packages. I think I would even go as far as deprecate payum/payum, or turn it into a shallow metapackage to discourage other projects from depending directly on it, because payment methods used by each downstream application are vastly different and I don't see much sense in providing stuff that ends up unused by default. I already convinced Sylius to do that (Replace payum/payum dependency with payum/core Sylius/Sylius#14766), but I think it would make sense for other projects to follow that strategy as well. After all, nobody should need Authorize.net, Be2Bill, Klarna, Offline, Payex, Paypal, Skeleton, Sofort and Stripe all at once! :) And even if they do, I believe it would be better to depend on specific packages explicitly instead of relying on a bundle monopackage.
• I'm also not sure why bridges to Laminas, Symfony and some other packages are part of the core. Perhaps they also could and should be extracted into their own packages, or moved into the appropriate bundles/extensions that already exist?
• Wouldn't changes like "moving away from ArrayObjects" break the API?

[pierredup]

Symfony 5.4 remains in active maintenance until late 2024, and then in security support until late 2025, so I think it would be a bit premature to drop support for it so early. Is there a good enough justification to do that?

Actually, I didn't look at Symfony's roadmap, I just somehow assumed that 5.4 will end maintenance when 6.4 is released (didn't think Symfony would maintain 2 LTS and a new major version together).

Based on this, I'm happy to continue supporting Symfony 5

I think I would even go as far as deprecate payum/payum, or turn it into a shallow metapackage to discourage other projects from depending directly on it

This was also discussed somewhere (can't find the issue or comments now), but I'm generally in favour of discouraging the install of payum/payum directly and rather installing payum/core along with the gateways needed

I'm also not sure why bridges to Laminas, Symfony and some other packages are part of the core. Perhaps they also could and should be extracted into their own packages, or moved into the appropriate bundles/extensions that already exist?

This makes development easier. If there are any changes to the Core packages, the bridges can be updated in the same go (and you don't have to wait for a new release of core in order to make the bridges compatible). I'll give this one some more thought. I like the idea of having them as separate packages, but also don't want to increase the maintenance burden.

Wouldn't changes like "moving away from ArrayObjects" break the API?

Not necessarily. There are lots of places where an ArrayObject is used internally for config and then just return an array (E.G in the GateWayFactory

Payum/src/Payum/Core/GatewayFactory.php

Lines 30 to 39 in b4ef678

	public function createConfig(array $config = [])
	{
	$config = ArrayObject::ensureArrayObject($config);
	$config->defaults($this->defaultConfig);
	$config->defaults($this->coreGatewayFactory->createConfig((array) $config));
	$this->populateConfig($config);
	return (array) $config;
	}

)

Instances like this can safely move away from using ArrayObject to something else without any breaking changes

[rimas-kudelis]

One more thing that would be great to consider is developer documentation on writing a gateway properly. The existing docs on developing a gateway are very short and don't delve deep into the logic of Payum, which means it's not easy to get this right and makes the initial learning curve rather steep. When I was writing adeoweb/sylius-everypay-plugin (Sylius payment plugin and a Payum gateway), I ended up enlisting @Prometee for help on making it at least somewhat proper code-wise, because my initial attempt turned out to be simply not correct from an architectural standpoint (although I think it worked). A step-by-step guide built on an existing typical gateway (or a couple different typical gateways – e.g. one where you simply redirect the user and then process the response, and the other where you also present them with payment choices and whatnot first) would be great.

BTW we actually attempted to collaborate on revamping the docs, but never finished this, so there's not much to show yet... :(

[pierredup]

Related: #991