PRE-3684: Deprecate Payum

[adumont-payplug]

So the conclusion holds — these actions never execute — but for a different reason than the ticket
gives: there is no payum.gateway_factory_builder for any payplug* factory, because
PayPlugSyliusPayPlugExtension::load() does not load config/services/gateway.xml, the only file
holding those tags. With no gateway to attach to, the tagged actions are collected and then never
run. That is the wording used throughout, so the next person to read it gets the real mechanism.

Deprecated

• Action\CaptureAction, StatusAction, NotifyAction, ConvertPaymentAction — each now names its
  live replacement in src/Command/Handler/ instead of the bare /** @deprecated */ they carried
• Action\Api\ApiAwareTrait::setApi()
• Gateway\AbstractGatewayFactory::populateConfig()
• config/services/gateway.xml

Deliberately NOT deprecated — three places where the obvious wider annotation would have been wrong:

Left alone	Why
ApiAwareTrait itself	Controller\OneClickAction is a routed controller that uses the trait for its $payPlugApiClient property, assigning it from PayPlugApiClientFactory. Only setApi(), the Payum ApiAwareInterface entry point, is dead. The trait carries a note saying so.
AbstractGatewayFactory the class	Still the home of FACTORY_NAME, FACTORY_TITLE and BASE_CURRENCY_CODE, referenced throughout the plugin. Only populateConfig() is annotated.
the api_client.* block in client.xml	Live wiring, not Payum wiring — #[Autowire]d into seven services. Per the PRE-3682 correction on the ticket, untouched.

Why deprecate rather than delete. gateway.xml's own header offers it as an opt-in escape
hatch, so a host application could be importing it and removal would be a BC break.

Removal target. UPGRADE.md gains a "Deprecations" section listing everything above, stating
removal in early 2027, and making clear that an application which does not import gateway.xml
itself is affected in no way and has nothing to migrate.

CHANGELOG.md was left alone: its top section is still ## [2.0.0] - Unreleased while 2.2.0 and
2.3.0-rc0 are tagged, so a ### Deprecated entry there would have landed under a misleading
heading. Happy to add one if you'd rather.

Motivation: the dead code actively misleads. The PRE-3630 spike spent real effort tracing a
wrong-account bug through payum.http_client → payum.api.http_client → Gateway::execute() →
ApiAwareTrait::setApi() before establishing that none of it runs. The sleep(10) in
NotifyAction::execute() was likewise documented as load-bearing; it is dead, and now says so.

Related issue(s): PRE-3684 — follow-up 3/4
from the PRE-3630 spike, parent epic
PRE-3440

Base branch: targets feature/PRE-3440_multi_shop_configuration, matching the sibling tickets
(#329, #330).

---

Type of Change

• 📝 Documentation update

No runtime code changed. trigger_deprecation() was deliberately not used: the code never executes,
so a runtime notice could never fire. PHPDoc @deprecated only.

---

Checklist

Code Quality

• Code is linted and formatted — ECS clean (196 files); PHPStan level max clean, 0 errors and no
  new baseline entries (phpstan-deprecation-rules is not installed, so @deprecated costs
  nothing statically)
• No unnecessary commented-out code or debug logs
• No hardcoded values (use env variables or config)

Testing

• Unit tests added / updated — none needed, and none added: the diff is docblocks, comments and
  one Markdown section. The existing suite is unchanged and green, 601 tests, 1128 assertions.
• New/changed code is covered by tests — no new executable code, so there is nothing for the
  coverage gate to measure on this diff

Also verified, since "no behaviour change" is the whole claim of this PR:

• bin/console lint:container passes on a real Sylius application with the plugin installed
• config/services/gateway.xml still parses as well-formed XML (it is only ever loaded by a host
  application that opts in, so a syntax error there would not surface in our own CI)

Security & Ops

• No sensitive data or secrets introduced
• Logging and error handling are appropriate — untouched