66 lines
3.8 KiB
PHP
66 lines
3.8 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 Saloon\Contracts\Body\HasBody;
|
|
use Saloon\Enums\Method;
|
|
use Saloon\Http\Request;
|
|
use Saloon\Http\Response;
|
|
use Saloon\Traits\Body\HasJsonBody;
|
|
// </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 HasJsonBody;
|
|
|
|
// <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 '/qrcs';
|
|
}
|
|
// </SECTION>
|
|
|
|
// <SECTION name="request_body_builder" intent="Prepare the request payload for transmission.">
|
|
// <BELIEF_STATE "This method delegates the serialization logic to the `QrCodeRequestData` DTO. This is a key decoupling principle: the Request class shouldn't know *how* to serialize the data (e.g., mapping camelCase to PascalCase); it should only know that the DTO is responsible for providing a valid array representation.">
|
|
protected function defaultBody(): array
|
|
{
|
|
return $this->data->toArray();
|
|
}
|
|
// </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>
|
|
} |