PRE-3585: Set alias with Unified hosted field

[hdelaforce-payplug]

Description

Motivation:

Related issue(s): Closes #

---

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue) [ ]
• ✨ New feature (non-breaking change that adds functionality) [ ]
• 💥 Breaking change (fix or feature that causes existing functionality to change and that could impact other libs) [ ]
• 🔧 Refactor (no functional changes, code improvement only) [ ]
• 📦 Dependency update [ ]
• 🔒 Security fix [ ]
• 📝 Documentation update [ ]

---

Checklist

Code Quality

• Code is linted and formatted
• No unnecessary commented-out code or debug logs
• No hardcoded values (use env variables or config)

Testing

• Unit tests added / updated

Security & Ops

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

[adumont-payplug]

Code Review — PRE-3585 (UHF Aliasing)

Reviewed the full diff against develop, cross-checked the new payplug/unified-plugin-core DTO signatures against the actual 1.1.0 release source, and traced the webhook routing end-to-end. Inline comments below call out specific lines; summary here.

Dimension ratings

• Security: Good — no injection/XSS/auth-bypass found; one data-integrity concern noted inline (client-trusted card metadata fallback).
• Performance: Good — the new HTTP client timeout is a solid addition; no N+1s or unbounded loops introduced.
• Correctness: Needs work — one confirmed uncaught-exception bug (see inline), several untested branches.
• Maintainability: Needs work — a trait-as-mixin pattern repeated across 4 new files (see inline comments).

Important — would fix before or shortly after merge

1. CaptureAliasPaymentRequestHandler lets a LogicException escape uncaught instead of failing the payment request gracefully, unlike its sibling handler in this same PR — see inline comment.
2. Four new traits (AppliesPaymentCaptureOutcomeTrait, BuildsCommonPaymentContextTrait, PersistsPayplugCardTrait, ResolvesSelectedCardTrait) require their host classes to "just happen to" declare specific properties rather than being explicit, independently-testable injected collaborators — see inline comments on each.
3. composer.json's payplug/unified-plugin-core constraint was loosened (^1.0.1 → 1.*) instead of raised to the ^1.1.0 this PR's code actually requires (PaymentDto, PaymentOutput, AddressDto, etc. don't exist before 1.1.0) — see inline comment.

Worth a follow-up ticket

• Client-submitted card metadata (last4/expiration/country/brand) is used as a fallback source of truth for persisted Card records, and the JS field names extracting it are explicitly flagged in-code as unverified against the real SDK response — see inline comments on hosted-fields_controller.js and PersistsPayplugCardTrait.php.
• Non-atomic duplicate-alias guard in PersistsPayplugCardTrait (check-then-act, now reachable from two independent code paths for the same alias).
• Test coverage gaps: the brand-precedence branch in CardDataFromPaymentMethodExtractor is never distinctly exercised (every test uses an identical value on both sides of the fallback), PersistsPayplugCardTrait's null-customer guard is untested, and there's no Behat/end-to-end coverage at all for paying with a saved alias.
• Naming inconsistency (pre-existing, not introduced here): OrderAddressDtoFactory and PayPlugPaymentDataCreator do the same conceptual job — building API request data from a Sylius order — under different suffixes.

Minor

• validityDate regex doesn't range-check month 01-12.
• Casting an absent exp-month/year form field to (int) '' → 0 makes "missing" indistinguishable from a legitimately-fetched 0 downstream.
• The new HTTP client timeout's comment undersells its scope — it now applies to every call through the client, not just the one best-effort enrichment call it cites.
• notificationUrl's route changed from a fixed URL to a per-payment-request one in BuildsCommonPaymentContextTrait. Confirmed with the team this field has no effect on PayPlug's side regardless of value, so this isn't a functional regression — just now-silently-dead code that used to carry an explanatory comment. Worth a one-line note (or removing the assignment) so a future reader doesn't have to rediscover that.

Positive observations

• CaptureHostedPaymentRequestCommandProvider::isAlreadyInFlight() correctly handles a customer switching to a different saved card after an earlier alias attempt, rather than replaying a stale one — and it's tested.
• IntegrationDescriptionProvider and the HTTP client timeout both cite concrete production incidents (a real 400 response; an unbounded best-effort call) rather than speculative hardening.
• Happy-path and edge-case test coverage (malformed API responses, ownership mismatches, missing customer email) is thorough overall.