>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3618948. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !48 >>> <p>A contributor arriving at Kessai knows Drupal, not Kessai. Every word we invent for something core already names is a word they have to learn for no reason. This audit checked every class, interface, enum, method, property, constant, plugin id, entity type, base field, route, service id, permission and config key in the module and its four submodules against core's own vocabulary, and fixes the places where we spent a word core does not use for something core does name. It is the sibling of Orchestra's <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/orchestra/issues/3618935" title="Status: Closed (fixed)">#3618935: Name things the way Drupal core does: canceled, core's *Hooks suffix, summary() over explain(), delete() over forget(), action over act</a></span>, run the same way and reaching the same kinds of finding.</p> <h3>How it was checked</h3> <p>Every candidate word was counted against a corpus of 24,164 identifiers taken from core's class, interface, trait, enum and method names in <code>core/lib</code> and <code>core/modules</code>. Kessai's 44 production PHP files declare 216 identifiers built from 183 distinct words, of which 49 have zero hits in that corpus. A word with zero hits is an invention. An invention is only a defect where core already has a word for the same thing; where the domain is genuinely outside core, the invention is correct and is deliberately kept below.</p> <h3>Already correct, and left alone</h3> <p>All 72 PHP files that declare a type are named for it. All 9 interfaces end <code>Interface</code>. The one enum is a bare noun with PascalCase cases, in core's style. All 7 gateway plugin ids and all 4 entity type ids are snake_case, all 26 distinct base field names are snake_case, all 6 route names are module-prefixed, the logger channel follows <code>logger.channel.kessai</code>, and the entity interfaces sit in the module root namespace with their classes under <code>Entity/</code>, exactly as core does for <code>NodeInterface</code> and <code>Node</code>. All 209 test method names pass the phpcs lowerCamel rule. Running phpcs with <code>--standard=Drupal,DrupalPractice</code> over the module root reports zero violations, so nothing below is a sniff failure; these are conventions the sniffs cannot see.</p> <h3>Proposed resolution</h3> <p><strong>American spelling.</strong> <code>cancelled</code> appears on 105 lines, 42 of them in production PHP, including the stored state constant <code>PaymentInterface::STATE_CANCELLED = 'cancelled'</code> and the event names <code>PaymentEvents::CANCELLED = 'kessai.cancelled'</code> and <code>PARTIALLY_CANCELLED = 'kessai.partially_cancelled'</code>. Core spells it <code>canceled</code> 51 times against 9 across its PHP, YAML, Twig and JavaScript. Kessai is pre-1.0 and reinstall-only, so the stored state value is free to change. Orchestra settled the same question the same way in <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/orchestra/issues/3618935" title="Status: Closed (fixed)">#3618935: Name things the way Drupal core does: canceled, core's *Hooks suffix, summary() over explain(), delete() over forget(), action over act</a></span>, so this also keeps the two modules spelling one word one way.</p> <p><strong>Hook classes take core's module prefix.</strong> Of core's 179 Hook classes outside test modules, 171 are named extension-then-topic-then <code>Hooks</code>, as in <code>NodeEntityHooks</code> and <code>ViewsThemeHooks</code>; the 8 exceptions are in <code>file</code>, <code>workspaces</code> and <code>system</code>. Kessai gets this right once, in <code>KessaiRequirements</code>. The others do not name their extension: <code>ViewsHooks</code> in kessai_views becomes <code>KessaiViewsEntityHooks</code> (it implements <code>hook_entity_type_alter</code>, not a Views hook, so the current name says the wrong thing twice), <code>WorldlineRequirements</code> becomes <code>KessaiWorldlineRequirements</code>, <code>SimulatorRequirements</code> becomes <code>KessaiSimulatorRequirements</code>, and the test module's <code>ClaimSpyHooks</code> becomes <code>KessaiTestHooks</code>.</p> <p><strong>The hook method is named after the hook.</strong> Every <code>#[Hook('cron')]</code> implementation in core is <code>public function cron()</code>. Ours is <code>onCron()</code>. Kessai's five other hook methods already follow the rule, so this is the one that drifted.</p> <p><strong>Agent nouns core never forms.</strong> <code>reaper</code>, <code>finalizer</code> and <code>spy</code> all have zero hits in core, against 527 <code>Provider</code>, 244 <code>Manager</code>, 231 <code>Handler</code>, 129 <code>Subscriber</code> and 35 <code>Processor</code>. <code>PaymentReaperHooks</code> implements <code>hook_cron</code> and nothing else, so it becomes <code>KessaiCronHooks</code>, matching core's own <code>AnnouncementsFeedCronHooks</code>; the reaper wording follows it out of the docblocks and two test method names. <code>WorldlinePaymentFinalizer</code> becomes <code>WorldlinePaymentHandler</code>. <code>PaymentAuditTrailBridge</code> sits in an <code>EventSubscriber</code> directory and does not end <code>Subscriber</code>, which 95 of core's 109 do; core's only two <code>Bridge</code> identifiers are <code>AnnotationBridgeDecorator</code> and <code>AttributeBridgeDecorator</code>, where the noun is <code>Decorator</code>. It becomes <code>PaymentAuditTrailSubscriber</code>, and its callback <code>record()</code> becomes <code>onPaymentEvent()</code>, since core's subscriber callbacks are <code>on</code> plus the event.</p> <p><strong>Booleans say is, has or should.</strong> Core declares 172 methods matching <code>is</code>, <code>has</code>, <code>should</code> or <code>can</code> returning <code>bool</code>, against 4 spelled <code>get</code>. Ours: <code>PaymentInterface::getStoreCard()</code> becomes <code>shouldStoreCard()</code> (the paired <code>setStoreCard()</code> is already core-shaped and stays), <code>PaymentInterface::holdKept()</code> becomes <code>isHoldKept()</code> and sits two methods from <code>isHoldOpen()</code> in the same interface, <code>WorldlineClientFactoryInterface::webhooksConfigured()</code> becomes <code>hasWebhooksConfigured()</code>, <code>WorldlineGateway::paymentAccepted()</code> and <code>paymentCancelledByConsumer()</code> become <code>isPaymentAccepted()</code> and <code>isPaymentCanceledByConsumer()</code>, and the private <code>PaymentManager::deferrable()</code> becomes <code>isDeferrable()</code>.</p> <p><strong>Accessors say get.</strong> Core's interfaces declare 2,044 distinct methods, of which 747 begin <code>get</code> and 237 <code>set</code>. Kessai's entity interfaces do this throughout, and two of its service interfaces do not. <code>WorldlineClientFactoryInterface</code> gains the prefix on <code>client()</code>, <code>pspid()</code>, <code>webhooksHelper()</code> and <code>checkoutSetting()</code>; <code>PaymentManagerInterface</code> gains it on <code>claims()</code>, <code>refunds()</code> and <code>reversals()</code>, which read as verbs today and are not.</p> <p><strong>Static factories say from.</strong> Core's value objects build through <code>create</code> (99 in <code>core/lib</code>) or <code>from</code> (23), never a bare noun. <code>PaymentDeadline::seconds(600)</code> becomes <code>fromSeconds(600)</code>, which also stops it colliding with <code>toSeconds()</code> on the same class, where one returns a deadline and the other an integer. <code>never()</code> and <code>siteDefault()</code> read as the constants they are and stay.</p> <p><strong><code>PaymentOperationKey::for()</code> is a PHP reserved keyword.</strong> Core declares no method called <code>for</code>. It is also the odd one out beside its own <code>forCapture()</code>, <code>forRefund()</code> and <code>forReversal()</code>, so it becomes <code>forOperation()</code>.</p> <p><strong>Service ids follow core's shapes.</strong> Core names all 63 of its plugin manager services <code>plugin.manager.</code> plus the plugin type, so <code>kessai.gateway_manager</code> becomes <code>plugin.manager.kessai_payment_gateway</code>, which also stops the id saying <code>gateway</code> while its class says <code>PaymentGatewayManager</code>. <code>kessai_worldline.client</code> resolves to <code>WorldlineClientFactory</code> and not to a client, so it becomes <code>kessai_worldline.client_factory</code>, following <code>http_client_factory</code>, <code>cache_factory</code> and <code>image.factory</code>.</p> <p><strong>Identifiers named for what they hold.</strong> <code>PaymentManagerInterface::latestMovement()</code> takes a parameter called <code>$movement</code> that holds an entity type id (<code>kessai_claim</code>, <code>kessai_refund</code>, <code>kessai_reversal</code>), so it becomes <code>$movement_type_id</code>. <code>PaymentManager::siblingsCarrying($payment, $alias)</code> is passed the value of the <code>token</code> base field, which <code>getToken()</code> and <code>latestToken()</code> both call a token, and in Drupal <code>alias</code> means a URL alias; the parameter becomes <code>$token</code> and the method becomes <code>loadSiblingsWithToken()</code>. <code>PaymentHandoffController::onwardUrl()</code> and <code>WorldlineReturnController::destination()</code> compute the same thing under two names, and core has 88 <code>destination</code> identifiers against zero <code>onward</code>, so both become <code>destination()</code>.</p> <p><strong>Smaller ones.</strong> <code>forgetCard()</code> becomes <code>deleteStoredCard()</code>: <code>forget</code> has zero hits in core against 278 <code>delete</code>, and Orchestra retired the same verb for the same reason in <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/orchestra/issues/3618935" title="Status: Closed (fixed)">#3618935: Name things the way Drupal core does: canceled, core's *Hooks suffix, summary() over explain(), delete() over forget(), action over act</a></span>. In <code>kessai_worldline.settings</code> the keys <code>api.api_key</code> and <code>api.api_secret</code> stutter inside their own <code>api</code> mapping and become <code>api.key</code> and <code>api.secret</code>. <code>KessaiRequirements::bcmath()</code> is named after a PHP extension rather than after what it does, and becomes <code>checkBcmath()</code>. The test gateway plugin ids are <code>stub</code>, <code>stub_decline</code> and <code>stub_capture_decline</code>, but the fourth is <code>session_stub</code>, so it becomes <code>stub_session</code>. <code>PaymentExpiryTest</code> still says <code>ttl</code> in two method names and three docblocks for what the code, the config key and the settings form all now call a deadline. The test double <code>ExtendedPaymentStorageSchema</code> moves into a <code>Stub</code> namespace, where kessai_audit_trail already keeps <code>RecordingAuditTrail</code>.</p> <h3>Deliberately kept</h3> <p>Core has no word for a payment engine's furniture, so these stay exactly as they are and a later sweep must not "fix" them: payment, gateway, checkout, claim, refund, reversal, movement, handoff, hold, capture, charge, deadline, kind, subject, reference, token, webhook, idempotency, reconcile, balance, currency, declined, transient, retryable, pspid. <code>ReconcileOutcome</code> stays too: <code>outcome</code> has zero hits in core, and Orchestra's audit already kept the same word for the same reason.</p> <h3>Deliberately not in this change</h3> <p>Four of these renames are visible to the two modules that consume Kessai: the service id, <code>forgetCard()</code>, <code>claims()</code> and <code>refunds()</code>, and the <code>CANCELLED</code> constants. That is eleven lines across eight files, resolved through each file's <code>use</code> statements so Yoyaku's own identically named <code>STATE_CANCELLED</code> constants are not counted. They are filed separately, with the line lists, as <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-3"><a href="https://www.drupal.org/project/yoyaku/issues/3618956" title="Status: Closed (duplicate)">#3618956: Track Kessai's renamed payment API: plugin.manager.kessai_payment_gateway, deleteStoredCard(), getClaims()/getRefunds() and STATE_CANCELED</a></span> for Yoyaku (eight lines) and <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/orchestra/issues/3618957" title="Status: Closed (fixed)">#3618957: Track Kessai's renamed payment API: plugin.manager.kessai_payment_gateway, deleteStoredCard() and STATE_CANCELED</a></span> for Orchestra (three lines).</p> <p>Two of the eleven are fatal rather than cosmetic: the service id is resolved from the container by name, and the event constant is a compile-time class reference, so either one left stale fails container compilation and takes the site down. Kessai therefore must not land ahead of those two issues. Nothing downstream reads the raw <code>'cancelled'</code> string or the raw event name, only the constants, so the stored value changes are transparent on their own, and Kessai being pre-1.0 and reinstall-only means no stored value needs migrating.</p> <h3>Correction: four of these did not land here</h3> <p>What merged did the <code>reaper</code> and <code>spy</code> half of the agent-noun group and stopped there. <code>WorldlinePaymentFinalizer</code>, <code>PaymentAuditTrailBridge</code>, its <code>record()</code> callback and <code>WorldlineGateway::paymentAccepted()</code> were all still in the code after this issue was marked fixed, so the section above described work the merge request did not carry. A second audit found it, and they land in <span class="drupalorg-gitlab-issue-link project-issue-status-info project-issue-status-7"><a href="https://www.drupal.org/project/kessai/issues/3619065" title="Status: Closed (fixed)">#3619065: Finish the renames #3618948 promised, and take core's verbs for takeOperationLock, defaultDeadline and latestMovement</a></span> along with three this audit missed: <code>takeOperationLock()</code>, <code>defaultDeadline()</code> and <code>latestMovement()</code>. Recorded here rather than edited out, so the gap between what was proposed and what shipped stays visible.</p> <p>AI-Generated: Yes (Claude Code was used to help draft this issue summary and to run the measurements it quotes. I reviewed it before posting; there is no code on this issue yet.)</p>