>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3621918. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !63 >>> <h3>Problem/Motivation</h3> <p>A full read of all 140 tracked files in the module rather than a diff against the last tag, plus phpcs and cspell at the configuration CI actually fetches, phpstan at level 5, potx per project across all five .po files, and a regeneration of the metrics page. Eleven findings.</p> <p>Three are defects a live site reaches:</p> <ul> <li><strong>An undone checkout could move money and leave no row.</strong> When the engine rejects a checkout the provider has already collected, <code>WorldlinePaymentHandler::releaseOrRefund()</code> hands the money back and writes a claim row and a refund row, so the merchant console never carries a refund this site cannot account for. A created provider payment that states no amount never passes <code>amountMatches()</code>, so it always reaches that method, and <code>recordCheckoutUndone()</code> was then handed a figure of zero and returned without writing anything. The undo itself still went out and asked Worldline for the whole payment.</li> <li><strong>One payment could stop the expiry sweep for good.</strong> <code>PaymentManager::loadGateway()</code> let the plugin manager's <code>PluginNotFoundException</code> escape, and that is not a class any caller of this engine declares or catches. The cron sweep therefore aborted at the first due payment whose gateway module was gone, and aborted again on every later run, because expiring that payment is exactly what the aborted sweep would have done. The handoff route caught only <code>GatewayException</code>, so a payer met a server error on the one route that exists to tell them nothing has been charged. And <code>deleteStoredCard()</code> runs over a batch, so one such payment left every card after it in the list unforgotten. A payment outlives the module that took it: kessai_simulator's own status report says to uninstall it before going live, and the documented example for <code>hook_kessai_gateway_info_alter()</code> takes a gateway out of the list outright.</li> <li><strong>The simulator checkout page went stale for the payer it is built for.</strong> Core keeps a form out of the page caches only for an authenticated visitor, because the zero max-age rides on the form token and that token is only added for one. The stand-in hosted page states an amount and a payment state and declares no cacheability of its own, so an anonymous payer who paid and came back was served the page they saw before, Pay button and all, instead of being told the payment had settled. It is the third payer-facing route in the project and the only one without <code>no_cache</code>.</li> </ul> <p>One is a break waiting on a dependency release: <code>AuditTrailInterface::event()</code> has gained a seventh parameter, and a class implementing an interface with fewer parameters than it declares is a fatal at class load. So <code>RecordingAuditTrail</code> takes the whole of <code>PaymentAuditTrailSubscriberTest</code> down the moment audit_trail cuts its next release. #3620931 was the same defect. CI cannot see it, because CI installs the current release; phpstan at level 5 run against a newer checkout is what reports it.</p> <p>The rest are duplication, accessibility, a Drupal standard and stale documentation:</p> <ul> <li>Worldline's two provider status categories, <code>COMPLETED</code> and <code>PENDING_MERCHANT</code>, were written out as literals in two classes. <code>isPaymentAccepted()</code> exists so the two never disagree on what accepted means; which category means captured and which means authorized is the same fact with the same hazard, and it decides whether undoing a rejected checkout sends a refund or a reversal.</li> <li><code>WorldlineGateway::isTransient()</code> re-implemented the walk over the platform's structured error list that <code>WorldlineError</code> was created to own, so a formatter and a classifier could drift about what the platform said.</li> <li>All six charts on the metrics page carried <code>role="img"</code> with no accessible name. That role makes the element a leaf, so it hides the text labels drawn inside it too, and a screen reader announced only "image" on a page that is nothing but numbers. Nothing asserted the fix either, which this module's own SimulatorCheckoutTest calls out as one refactor away from being undone.</li> <li>Two <code>t()</code> calls in the Worldline settings form put an <code>@</code> placeholder inside an <code>href</code>, where Drupal reserves <code>:</code> for a URL. Not exploitable, since both come from <code>Url::fromRoute()</code>, but it is the documented rule and the same module already writes <code>:url</code> elsewhere.</li> <li><code>PaymentOperationKey::MAX_LENGTH</code> was private while the gateway guide tells a gateway author to read it, so following that instruction is a PHP error.</li> <li>Two documentation tables had gone behind the code: the movement table in index.md omitted <code>recordCheckoutUndone()</code>, which makes all three kinds of row, and the payment field table in architecture.md listed 22 of the entity's 24 base fields.</li> <li>metrics.md was measured two commits ago.</li> </ul> <h3>Proposed resolution</h3> <ul> <li>Write the undo rows against the payment's own amount when the provider names none, and log at error severity that the figure is this site's rather than the provider's. The request is unchanged: with no amount it asks for the whole payment, which is the right thing to ask when the amount is unknown.</li> <li><code>loadGateway()</code> says it once, in this module's own vocabulary: a <code>GatewayDeclinedException</code>, which every money path already documents and handles, and which is the right classification because reinstalling a module is not a retry. The sweep then treats it as <code>NothingHappened</code>, since nobody can be asked and nobody ever will be, which is the same reasoning <code>PaymentGatewayBase::reconcile()</code> already gives, and says so at warning severity. The stored-card batch takes its existing "nothing deletable at a provider" branch, and <code>settleOnGateway()</code> loads the gateway inside its own try so the two token paths record the decline they promise.</li> <li><code>no_cache: 'TRUE'</code> on the simulator checkout route, matching the two other payer-facing routes.</li> <li>Declare <code>$chain_only</code> on the stub. PHP lets an implementation accept extra optional parameters, so it satisfies the current release and the next one at once.</li> <li>Name the two status categories once on <code>WorldlineGateway</code>, read at all four sites. <code>WorldlineError::errors()</code> returns the platform's list as plain arrays, so <code>describe()</code> formats it and <code>isTransient()</code> classifies it and the probing is written once.</li> <li>Mark every generated chart <code>aria-hidden</code>, because every figure it draws is also in the table or the sentence beside it, and add the plugin table that was missing so that is true of the sixth as well. Pinned by a test asserting the attribute on the page that ships, since the generator's entry point reads stdin and exits and so cannot be included from a test.</li> <li>Both placeholders switched, and the two French msgids re-keyed so the existing translation moves with them.</li> <li><code>MAX_LENGTH</code> made public, the two documentation tables completed, metrics.md regenerated to a fixed point.</li> </ul> <p>Six new tests, each of which fails against the unfixed code: the four defect surfaces above, plus the accessible state of the charts. Three things were fixed without being reported, because no test could tell the two versions apart: a float comparison of money on the simulator checkout, a stray conjunction in README's event list, and one unwrapped line in architecture.md.</p> <p>Five audit rounds were then run over the branch itself, and four of them found something: the missing chart test; two names out of step with the module (a bare-noun data accessor where every other one is <code>get*</code>, against the pass #3619212 made, and a helper calling the real service "live" where this module already uses that word for three other things); the new exception documented on <code>create()</code> but not on the two token methods that propagate it; and three sentences that had stopped being true, including a <code>void</code> method still summarised as "Returns a card-verification charge". The fifth round found nothing. The diff adds no query on any path that previously completed: six query-issuing lines added against eight removed, each addition replacing a removal at the same point, with two inlined copies of one loop collapsed into a single owner.</p> <p>Playing the Drupal 12 lane, which is a manual job and had therefore sat skipped on every 1.x pipeline since 2026-09-05, turned it red on one line that predates this change: <code>user_role_grant_permissions()</code> in the simulator test's setUp(), deprecated in 11.5. phpstan reported it once, and phpunit passed 257 tests while still reporting a class as Failure, because run-tests.sh on core main adds --fail-on-deprecation and that call was the only deprecation in the whole run. Core's named replacement is the plural <code>RoleInterface::grantPermissions()</code>, which does not exist in 11.3, and this module declares ^11.3 || ^12, so the grant goes through the test base's own <code>UserCreationTrait::grantPermissions()</code> helper instead. Both Drupal 12 jobs are green.</p> <h3>Remaining tasks</h3> <p>Review and merge.</p> <h3>User interface changes</h3> <p>The simulator checkout page is no longer served from a cache, so it always shows the payment's current state. The metrics page gains a table of plugins by type, and its charts are marked decorative.</p> <h3>API changes</h3> <p><code>PaymentOperationKey::MAX_LENGTH</code> becomes public. <code>PaymentManagerInterface::create()</code>, <code>::authorizeToken()</code> and <code>::chargeToken()</code> now document <code>GatewayDeclinedException</code> for a gateway plugin id that names nothing installed; every other money operation already documented it. <code>WorldlineGateway</code> gains two public constants for the provider's status categories. Nothing is removed and no signature changes.</p> <h3>Data model changes</h3> <p>None.</p> <h3>Release notes snippet</h3> <p>A checkout the engine rejects after the provider has collected it is now recorded even when the provider states no amount, so money that moved always leaves a claim and a refund row. A payment naming a gateway this site no longer has is expired on its local deadline instead of stopping the expiry sweep, tells the payer instead of erroring at the handoff, and no longer stops a stored-card delete part way through a batch. The payment simulator's checkout page is never served from a cache. The metrics page's charts no longer read to a screen reader as images with no name.</p> <p>AI-Generated: Yes (Claude Code was used to read the module, to draft this issue summary, and to write the fixes and their tests. I reviewed all of it, and each new test was confirmed to fail against the unfixed code.)</p>