README

此库解码按照斯洛伐克Pay By Square标准编码的字符串。

此包可以作为独立库或Symfony包使用

安装

composer require rikudou/pay-by-square-decoder

需求

您必须在系统中安装来自 xz-utils 的 xz 二进制文件。

用法

\Rikudou\BySquare\Decoder\PayBySquareDecoder 类有一个名为 decode 的公共方法，它接受一个包含编码数据的字符串参数。

示例

<?php

use Rikudou\BySquare\Decoder\PayBySquareDecoder;

$encodedData = '0006Q0000UAT63HVES6GL5A5A0O9NSPEEHUHIEP70EG9LM6LU6EBNQ8KG6RB2N2LUIHMVTV51KQ77DGFC25KM2S9V46EQSN5GSD9J1N4BKT1L9ASVOOT1LPOMAO66IS2BHJDCNA4D9LFKG9MTFLISBD36O5CQQNJIBB2TJILQVVN684000';
$decoder = new PayBySquareDecoder();

$decodedData = $decoder->decode($encodedData);
// $decodedData is now an instance of \Rikudou\BySquare\VO\DecodedBySquareData

如果 xz 二进制文件不在您的 PATH 中，您必须首先设置路径

<?php

use Rikudou\BySquare\Decoder\PayBySquareDecoder;

$decoder = new PayBySquareDecoder();
$decoder->setXzBinary('/path/to/xz');

$decodedData = $decoder->decode($encodedData);
// $decodedData is now an instance of \Rikudou\BySquare\VO\DecodedBySquareData

高级配置

\Rikudou\BySquare\Decoder\PayBySquareDecoder 将配置对象作为第一个参数，其中可以进行一些高级配置。

如果没有提供配置对象，将创建一个具有默认值的对象。

目前只有部分数据配置可用。

<?php

use Rikudou\BySquare\Decoder\PayBySquareDecoder;
use Rikudou\BySquare\Config\PayBySquareDecoderConfiguration;

$config = new PayBySquareDecoderConfiguration();
$config
    ->setAllowPartialData(false);

$decoder = new PayBySquareDecoder($config);

选项

• 允许部分数据
  • 类型: bool
  • 默认值: true
  • 方法: setAllowPartialData(bool) / isPartialDataAllowed()
  • 描述: 由于各种原因，xz 二进制文件有时会因意外的输入结束而失败，这通常不是问题。当设置为 true 时，即使 xz 认为它不完整，解码器也会接受部分数据。

Symfony 中的用法

如果您使用 Symfony flex，包应该自动配置，如果不这样做，只需将 \Rikudou\BySquare\RikudouPayBySquareDecoderBundle 添加到您的 config/bundles.php。

现在您可以使用 Rikudou\BySquare\Decoder\PayBySquareDecoder 作为服务

<?php
use Rikudou\BySquare\Decoder\PayBySquareDecoder;

class MyService
{
    /**
     * @var PayBySquareDecoder
     */
    private $decoder;
    
    public function __construct(PayBySquareDecoder $decoder)
    {   
        $this->decoder = $decoder;
    }
}

如果您的 xz 二进制文件不在您的路径中，您可以在 config/packages/rikudou_pay_by_square_decoder.yaml 中创建一个配置文件并更改路径，以下是默认配置（使用 config:dump 命令生成）

# Default configuration for extension with alias: "rikudou_pay_by_square_decoder"
rikudou_pay_by_square_decoder:

    # The path to the xz binary, null means auto detect
    xz_path:              null

    # Whether to continue even if decoding fails due to unexpected end of input and only partial data are available
    allow_partial_data:   true

返回值描述

decode 方法返回一个 \Rikudou\BySquare\VO\DecodedBySquareData 实例，这是一个值对象。方法名在大多数情况下是自解释的。

• getVersion(): int - 返回 Pay By Square 版本，目前仅支持版本 0
• getPaymentId(): ?string - 内部支付 ID
• getPaymentsCount(): int - 编码字符串中包含的支付次数
• isRegularPayment(): bool - 如果支付是标准一次性支付，则返回 true
• getAmount(): float - 支付金额
• getCurrency(): ?string - 三字母 ISO 货币代码
• getDueDate(): ?DateTime - 返回到期日期，如果没有提供到期日期则返回 1970-01-01 日期
• getVariableSymbol(): ?int - 如果存在则返回变量符号，否则返回 null
• getConstantSymbol(): ?int - 如果存在则返回常量符号，否则返回 null
• getSpecificSymbol(): ?int - 如果存在则返回特定符号，否则返回 null
• getPayerReference(): ?string - 返回付款人参考，例如变量、常量和特定符号作为单个字符串

注意：付款人参考和变量/常量/特定符号不是相互构造的，而是直接从支付数据中获取的，这意味着如果您在寻找例如变量符号时，您应该检查两者

• getNote(): ?string - 返回备注/评论
• getIbanCount(): int - 返回编码字符串中存在的 IBAN 数量
• getIban(): IBAN - 返回第一个 IBAN - 如果没有 IBAN 则抛出异常
• getIbans(): iterable<IBAN> - 返回所有存在的 IBAN 的可迭代对象
• isStandingOrder(): bool - 是否为定期支付
• isDirectDebit(): bool - 判断支付是否为直接借记
• getPayeeName(): ?string - 返回收款人名称
• getPayeeAddressLine1(): ?string - 返回收款人的地址行1
• getPayeeAddressLine2(): ?string - 返回收款人的地址行2

方法 getIban 和 getIbans 返回 \Rikudou\BySquare\VO\IBAN（或其可迭代对象），这是一个具有两个方法的简单值对象

• getIban(): ?string - 返回 IBAN
• getBic(): ?string - 返回 BIC/SWIFT 代码

异常处理

此库抛出的唯一异常是 \Rikudou\BySquare\Exception\PayBySquareException