71 lines
3.9 KiB
PHP
71 lines
3.9 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
/*
|
|
// MODULE_CONTRACT: Represents the "Get QR Code" (qrcs) API call within the SBP gateway.
|
|
// RESPONSIBILITY: To define the HTTP method, endpoint, request body structure, and response data mapping for generating an SBP QR code.
|
|
// INPUTS: QrCodeRequestData (DTO containing QR parameters).
|
|
// OUTPUTS: QrCodeResponseData (DTO containing the QR payload and image URL).
|
|
// LINKS: SbpConnector.php
|
|
*/
|
|
|
|
namespace Apoloz\AlfaBank\Sbp\Requests;
|
|
|
|
// <SECTION name="module_imports" intent="Import components required for defining the request and its data structures.">
|
|
// <BELIEF_STATE "A Request class needs its specific data transfer objects (DTOs) for the request payload and the response. It also requires Saloon's base classes and traits to function within the framework.">
|
|
use Apoloz\AlfaBank\Sbp\Data\QrCodeRequestData;
|
|
use Apoloz\AlfaBank\Sbp\Data\QrCodeResponseData;
|
|
use Apoloz\AlfaBank\Utils\CmsSigner;
|
|
use Saloon\Contracts\Body\HasBody;
|
|
use Saloon\Enums\Method;
|
|
use Saloon\Http\Request;
|
|
use Saloon\Http\Response;
|
|
use Saloon\Traits\Body\HasStringBody;
|
|
// </SECTION>
|
|
|
|
// <SECTION name="class_definition" intent="Define a class that encapsulates all information for the 'Get QR Code' API call.">
|
|
// <BELIEF_STATE "Using a dedicated class for each API request is a core Saloon pattern. It organizes the endpoint, method, body, and response handling into a single, reusable, and testable unit. Implementing `HasBody` and using `HasJsonBody` signals its intent to send a JSON payload.">
|
|
class GetQrCodeRequest extends Request implements HasBody
|
|
{
|
|
use HasStringBody;
|
|
|
|
// <SECTION name="http_method_declaration" intent="Declare the HTTP verb for this API operation.">
|
|
// <BELIEF_STATE "The SBP specification requires a POST request to generate a QR code, as the operation creates a new resource on the server.">
|
|
protected Method $method = Method::POST;
|
|
// </SECTION>
|
|
|
|
// <SECTION name="constructor" intent="Inject the structured payload required to generate the QR code.">
|
|
// <BELIEF_STATE "Requiring a strongly-typed `QrCodeRequestData` DTO in the constructor is a deliberate design choice to enforce data integrity at compile time. This prevents developers from sending malformed or incomplete data to the API.">
|
|
public function __construct(
|
|
protected QrCodeRequestData $data
|
|
) {}
|
|
// </SECTION>
|
|
|
|
// <SECTION name="endpoint_resolver" intent="Define the specific URI for the QR code generation endpoint.">
|
|
// <BELIEF_STATE "Centralizing the endpoint path in this method makes the SDK resilient to API changes. If the endpoint moves from '/qrcs' to '/v2/qrcs', this is the only line that needs to be updated for this specific request.">
|
|
public function resolveEndpoint(): string
|
|
{
|
|
return '/';
|
|
}
|
|
// </SECTION>
|
|
|
|
// <SECTION name="request_body_builder" intent="Prepare the request payload for transmission.">
|
|
// <BELIEF_STATE "This method builds the request body by adding the required 'command' field and merging the DTO data. The SBP API requires the 'command' field to identify the operation type. The 'GetQRCd' command is used for both static and dynamic QR code generation.">
|
|
protected function defaultBody(): string
|
|
{
|
|
$bodyArray = array_merge(
|
|
['command' => 'GetQRCd'],
|
|
$this->data->toArray()
|
|
);
|
|
return CmsSigner::canonicalize($bodyArray);
|
|
}
|
|
// </SECTION>
|
|
|
|
// <SECTION name="response_dto_caster" intent="Transform the raw API JSON response into a structured DTO.">
|
|
// <BELIEF_STATE "Automatically casting the JSON response to a `QrCodeResponseData` DTO provides a superior, type-safe developer experience. It abstracts away the raw response, allowing the user to interact with a clean, predictable object with autocompletion and static analysis benefits.">
|
|
public function createDtoFromResponse(Response $response): QrCodeResponseData
|
|
{
|
|
return QrCodeResponseData::from($response->json());
|
|
}
|
|
// </SECTION>
|
|
} |