forked from apoloz/alfa-bank-sdk
74 lines
4.5 KiB
PHP
74 lines
4.5 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
/*
|
|
// MODULE_CONTRACT: Defines the structure and mapping for the request payload when generating an SBP QR Code.
|
|
// RESPONSIBILITY: To ensure type safety, enforce expected data types, and handle property name mapping between internal (camelCase) and external (PascalCase/API) conventions.
|
|
// INPUTS: Raw data array (typically from user input or internal system).
|
|
// OUTPUTS: A validated, strongly-typed object representing the QR code generation request.
|
|
// LINKS: GetQrCodeRequest.php (uses this DTO)
|
|
*/
|
|
|
|
namespace Apoloz\AlfaBank\Sbp\Data;
|
|
|
|
// <SECTION name="module_imports" intent="Import necessary attributes and base class for defining the DTO.">
|
|
// <BELIEF_STATE "Spatie's Laravel Data package provides powerful features for DTOs, including automatic mapping, validation, and serialization. Using its attributes (`MapName`, `Data`) simplifies the DTO's definition and functionality.">
|
|
use Spatie\LaravelData\Attributes\MapName;
|
|
// Note: Not used directly here, but generally relevant for output mapping
|
|
use Spatie\LaravelData\Data;
|
|
|
|
// Note: Not directly used, but part of the Spatie Data ecosystem
|
|
// </SECTION>
|
|
|
|
// <SECTION name="class_definition" intent="Define the DTO for an SBP QR Code generation request.">
|
|
// <BELIEF_STATE "A dedicated DTO for the QR code request ensures that the input data for the API call is always structured correctly and explicitly typed. This significantly improves code readability, maintainability, and prevents common API integration bugs.">
|
|
class QrCodeRequestData extends Data
|
|
{
|
|
// <SECTION name="constructor_properties" intent="Define all properties that constitute the QR code request payload, including API name mappings.">
|
|
// <BELIEF_STATE "Each property explicitly defines its type and optionality. Crucially, `#[MapName]` attributes are used to bridge the gap between internal PHP `camelCase` naming conventions and the external API's `PascalCase` requirements, maintaining a clean internal API while satisfying external constraints.">
|
|
public function __construct(
|
|
// <BELIEF_STATE "The `TermNo` is a mandatory identifier for the payment terminal. Using `#[MapName]` allows the internal property to be `termNo` (camelCase) while the API expects `TermNo` (PascalCase).">
|
|
#[MapName('TermNo')]
|
|
public string $termNo,
|
|
|
|
// <BELIEF_STATE "The `qrcType` specifies whether the QR code is static ('01') or dynamic ('02'). Providing a default value simplifies usage for the most common scenario.">
|
|
#[MapName('qrcType')] // Although same name, good to be explicit
|
|
public string $qrcType = '01',
|
|
|
|
// <BELIEF_STATE "The `amount` is optional for static QRs but mandatory for dynamic ones. It's stored as a string to avoid floating-point precision issues with currency.">
|
|
public ?string $amount = null,
|
|
|
|
// <BELIEF_STATE "The `currency` is typically 'RUB' for SBP, but it's explicitly defined for clarity and future extensibility.">
|
|
public string $currency = 'RUB',
|
|
|
|
// <BELIEF_STATE "The `paymentPurpose` provides a human-readable description for the payment, improving reconciliation.">
|
|
public ?string $paymentPurpose = null,
|
|
|
|
// <BELIEF_STATE "The `redirectUrl` is where the user is sent after completing the payment, essential for web-based flows.">
|
|
public ?string $redirectUrl = null,
|
|
|
|
// <BELIEF_STATE "The `messageID` provides an optional, unique identifier for the request, useful for idempotency or tracking.">
|
|
public ?string $messageID = null,
|
|
|
|
// <BELIEF_STATE "Width and height allow customization of the generated QR code image dimensions.">
|
|
public ?string $width = null,
|
|
public ?string $height = null,
|
|
|
|
// <BELIEF_STATE "The `queryData` specifies where the bank should send webhook notifications about payment status changes.">
|
|
public GetQRCdQueryData $queryData,
|
|
|
|
// Dynamic QR specific fields
|
|
// <BELIEF_STATE "The `OrderNumber` is specific to dynamic QRs, providing a unique identifier for the order in the merchant's system.">
|
|
#[MapName('OrderNumber')]
|
|
public ?string $orderNumber = null,
|
|
|
|
// <BELIEF_STATE "The `qrTtl` defines how long a dynamic QR code remains valid, specified in minutes.">
|
|
public ?string $qrTtl = null,
|
|
|
|
// <BELIEF_STATE "Subscription service identifiers are used for recurring payment scenarios with SBP.">
|
|
public ?string $subscriptionServiceId = null,
|
|
public ?string $subscriptionServiceName = null,
|
|
) {}
|
|
// </SECTION>
|
|
}
|