Add Euro and Foreign Transactions, refactor Domestic Transactions

.docs/README.md

@@ -31,16 +31,42 @@ fio:
 
 ## Usage
 
-As this package is under development we haven't included downloading payments from bank yet. You can use our package for simply sending domestic payments to bank. You can send multiple payments at once but you can query bank api only once in 30 seconds (if you ping servers in shorter intervals it will return error). This package only supports domestic transactions but it is very easy to implement other types of payments. You only need to extend `Contributte\Fio\Entity\Transaction\Transaction` class and use it same way as Domestic Transaction class which has these mandatory properties:
+As this package is under development we haven't included downloading payments from bank yet. You can use our package for simply sending payments to bank. You can send multiple payments at once but you can query bank api only once in 30 seconds (if you ping servers in shorter intervals it will return error). This package supports domestic transactions (`DomesticTransaction`), euro payments (`EuroTransaction`) and foreign payments (`ForeignTransaction`).
 
-* Sender account (automatically supplier from config)
-* Currency
+`DomesticTransaction` mandatory properties:
+
+* Sender account (automatically supplied from config)
+* Currency (default CZK)
 * Amount
 * Recipient account
 * Bank code
 * Date
 
-For more properties check the class itself.
+`EuroTransaction` mandatory properties:
+
+* Sender account (automatically supplied from config)
+* Currency (default EUR)
+* Amount
+* Recipient account (IBAN)
+* Date
+* Beneficiary name (`setBenefName()`)
+
+`ForeignTransaction` mandatory properties:
+
+* Sender account (automatically supplied from config)
+* Currency (account currency, default CZK)
+* Amount
+* Recipient account (account number or IBAN)
+* BIC
+* Date
+* Beneficiary name, street, city and country
+* Remittance info 1 (`setRemittanceInfo1()`)
+* Details of charges (`setDetailsOfCharges()`, `CHARGES_OUR`/`CHARGES_BEN`/`CHARGES_SHA`)
+* Payment reason (`setPaymentReason()`, see FIO API docs chapter 6.3.4)
+
+The bank requires transaction types in a fixed order within one batch (domestic, euro, foreign payments) — the library sorts the export automatically, you can add payments in any order.
+
+For more properties check the classes themselves.
 
 From `FioManager` you get `PaymentService` which has two methods:
 

src/Entity/Transaction/AbroadTransaction.php

@@ -0,0 +1,98 @@
+<?php declare(strict_types = 1);
+
+namespace Contributte\Fio\Entity\Transaction;
+
+/**
+ * AbroadTransaction (common fields of euro and foreign payments)
+ */
+abstract class AbroadTransaction extends Transaction
+{
+
+	protected string $benefName;
+
+	protected ?string $bic = null;
+
+	protected ?string $comment = null;
+
+	protected ?string $benefStreet = null;
+
+	protected ?string $benefCity = null;
+
+	protected ?string $benefCountry = null;
+
+	protected ?string $remittanceInfo1 = null;
+
+	protected ?string $remittanceInfo2 = null;
+
+	protected ?string $remittanceInfo3 = null;
+
+	public function setBenefName(string $benefName): void
+	{
+		$this->assertMaxLength($benefName, 35, 'benefName');
+
+		$this->benefName = $benefName;
+	}
+
+	/**
+	 * ISO 9362, pad 8-char BIC with XXX
+	 */
+	public function setBic(string $bic): void
+	{
+		$this->assertExactLength($bic, 11, 'bic');
+
+		$this->bic = $bic;
+	}
+
+	public function setComment(string $comment): void
+	{
+		$this->assertMaxLength($comment, 140, 'comment');
+
+		$this->comment = $comment;
+	}
+
+	public function setBenefStreet(string $benefStreet): void
+	{
+		$this->assertMaxLength($benefStreet, 35, 'benefStreet');
+
+		$this->benefStreet = $benefStreet;
+	}
+
+	public function setBenefCity(string $benefCity): void
+	{
+		$this->assertMaxLength($benefCity, 35, 'benefCity');
+
+		$this->benefCity = $benefCity;
+	}
+
+	/**
+	 * Country code of the account owner, see FIO API docs chapter 6.3.2
+	 */
+	public function setBenefCountry(string $benefCountry): void
+	{
+		$this->assertLengthBetween($benefCountry, 2, 3, 'benefCountry');
+
+		$this->benefCountry = $benefCountry;
+	}
+
+	public function setRemittanceInfo1(string $remittanceInfo): void
+	{
+		$this->assertMaxLength($remittanceInfo, 35, 'remittanceInfo');
+
+		$this->remittanceInfo1 = $remittanceInfo;
+	}
+
+	public function setRemittanceInfo2(string $remittanceInfo): void
+	{
+		$this->assertMaxLength($remittanceInfo, 35, 'remittanceInfo');
+
+		$this->remittanceInfo2 = $remittanceInfo;
+	}
+
+	public function setRemittanceInfo3(string $remittanceInfo): void
+	{
+		$this->assertMaxLength($remittanceInfo, 35, 'remittanceInfo');
+
+		$this->remittanceInfo3 = $remittanceInfo;
+	}
+
+}

src/Entity/Transaction/DomesticTransaction.php

@@ -2,8 +2,6 @@
 
 namespace Contributte\Fio\Entity\Transaction;
 
-use Contributte\Fio\Exceptions\InvalidPropertyException;
-
 /**
  * DomesticTransaction
  */
@@ -24,94 +22,60 @@ final class DomesticTransaction extends Transaction
 	// Příkaz k inkasu
 	public const PAYMENT_TYPE_COLLECTION = 431022;
 
-	private int $paymentType;
-
 	private string $bankCode;
 
-	private string $ks;
-
-	private string $vs;
+	private ?string $ks = null;
 
-	private string $ss;
+	private ?string $vs = null;
 
-	private string $messageForRecipient;
+	private ?string $ss = null;
 
-	private string $comment;
+	private ?string $messageForRecipient = null;
 
-	private int $paymentReason;
-
-	public function setPaymentType(int $paymentType): void
-	{
-		if (strlen((string) $paymentType) !== 6) {
-			throw new InvalidPropertyException('$paymentType has to be 6 digits long.');
-		}
-
-		$this->paymentType = $paymentType;
-	}
+	private ?string $comment = null;
 
 	public function setBankCode(string $bankCode): void
 	{
-		if (strlen($bankCode) !== 4) {
-			throw new InvalidPropertyException('$bankCode must be 4 digits long.');
-		}
+		$this->assertExactLength($bankCode, 4, 'bankCode');
 
 		$this->bankCode = $bankCode;
 	}
 
 	public function setKs(string $ks): void
 	{
-		if (strlen($ks) > 4) {
-			throw new InvalidPropertyException('$ks can be maximum of 4 digits long.');
-		}
+		$this->assertMaxLength($ks, 4, 'ks');
 
 		$this->ks = $ks;
 	}
 
 	public function setVs(string $vs): void
 	{
-		if (strlen($vs) > 10) {
-			throw new InvalidPropertyException('$vs can be maximum of 10 digits long.');
-		}
+		$this->assertMaxLength($vs, 10, 'vs');
 
 		$this->vs = $vs;
 	}
 
 	public function setSs(string $ss): void
 	{
-		if (strlen($ss) > 10) {
-			throw new InvalidPropertyException('$ss can be maximum of 10 digits long.');
-		}
+		$this->assertMaxLength($ss, 10, 'ss');
 
 		$this->ss = $ss;
 	}
 
 	public function setMessageForRecipient(string $messageForRecipient): void
 	{
-		if (strlen($messageForRecipient) > 140) {
-			throw new InvalidPropertyException('$messageForRecipient can be maximum of 140 characters long.');
-		}
+		$this->assertMaxLength($messageForRecipient, 140, 'messageForRecipient');
 
 		$this->messageForRecipient = $messageForRecipient;
 	}
 
 	public function setComment(string $comment): void
 	{
-		if (strlen($comment) > 255) {
-			throw new InvalidPropertyException('$comment can be maximum of 255 characters long.');
-		}
+		$this->assertMaxLength($comment, 255, 'comment');
 
 		$this->comment = $comment;
 	}
 
-	public function setPaymentReason(int $paymentReason): void
-	{
-		if (strlen((string) $paymentReason) !== 3) {
-			throw new InvalidPropertyException('$paymentReason must be 3 digits long.');
-		}
-
-		$this->paymentReason = $paymentReason;
-	}
-
 	/**
 	 * @return mixed[]
 	 */

src/Entity/Transaction/EuroTransaction.php

@@ -0,0 +1,100 @@
+<?php declare(strict_types = 1);
+
+namespace Contributte\Fio\Entity\Transaction;
+
+use Contributte\Fio\Exceptions\InvalidPropertyException;
+
+/**
+ * EuroTransaction (Europlatba, XML element T2Transaction)
+ */
+final class EuroTransaction extends AbroadTransaction
+{
+
+	public const NAME = 'T2Transaction';
+
+	// Standardní
+	public const PAYMENT_TYPE_STANDARD = 431008;
+
+	// Prioritní
+	public const PAYMENT_TYPE_PRIORITY = 431009;
+
+	// Okamžitá
+	public const PAYMENT_TYPE_INSTANT = 431018;
+
+	protected string $currency = self::EURO;
+
+	private ?string $ks = null;
+
+	private ?string $vs = null;
+
+	private ?string $ss = null;
+
+	/**
+	 * Recipient account is an IBAN (ISO 13616)
+	 */
+	public function setAccountTo(string $accountTo): void
+	{
+		if (preg_match('/^[A-Za-z]{2}\d{2}[A-Za-z0-9]{1,30}$/', $accountTo) !== 1) {
+			throw new InvalidPropertyException('$accountTo must be a valid IBAN (max 34 characters).');
+		}
+
+		$this->accountTo = $accountTo;
+	}
+
+	public function setKs(string $ks): void
+	{
+		$this->assertMaxLength($ks, 4, 'ks');
+
+		$this->ks = $ks;
+	}
+
+	public function setVs(string $vs): void
+	{
+		$this->assertMaxLength($vs, 10, 'vs');
+
+		$this->vs = $vs;
+	}
+
+	public function setSs(string $ss): void
+	{
+		$this->assertMaxLength($ss, 10, 'ss');
+
+		$this->ss = $ss;
+	}
+
+	/**
+	 * @return mixed[]
+	 */
+	public function toArray(): array
+	{
+		return array_merge(parent::toArray(), [
+			'ks' => $this->ks,
+			'vs' => $this->vs,
+			'ss' => $this->ss,
+			'bic' => $this->bic,
+			'date' => $this->date,
+			'comment' => $this->comment,
+			'benefName' => $this->benefName,
+			'benefStreet' => $this->benefStreet,
+			'benefCity' => $this->benefCity,
+			'benefCountry' => $this->benefCountry,
+			'remittanceInfo1' => $this->remittanceInfo1,
+			'remittanceInfo2' => $this->remittanceInfo2,
+			'remittanceInfo3' => $this->remittanceInfo3,
+			'paymentReason' => $this->paymentReason,
+			'paymentType' => $this->paymentType,
+		]);
+	}
+
+	public function isValid(): bool
+	{
+		return isset(
+			$this->accountFrom,
+			$this->amount,
+			$this->accountTo,
+			$this->date,
+			$this->benefName
+		);
+	}
+
+}