rikudou / czqrpayment
QR payment library for Czech accounts
Installs: 250 217
Dependents: 6
Suggesters: 0
Security: 0
Stars: 26
Watchers: 4
Forks: 7
Open Issues: 0
Requires
- php: ^7.3 | ^8.0
- rikudou/iban: ^1.1.1
- rikudou/qr-payment-interface: ^1.0
- rikudou/qr-payment-qr-code-provider: ^1.0
Requires (Dev)
- endroid/qr-code: ^3.2
- friendsofphp/php-cs-fixer: ^2.18
- php-coveralls/php-coveralls: ^2.1
- phpstan/phpstan: ^0.12.82
- phpunit/phpunit: ^9.5
Suggests
- endroid/qr-code: For getting the qr code image
README
A simple library to generate QR payment code for Czech Republic. All methods are documented in source code.
See also QR code payment generator for Slovak, Hungarian or European Union accounts.
Using Symfony? See the QR Payment Bundle.
Installation
Via composer: composer require rikudou/czqrpayment
Usage
You can create the QR payment for an object implementing \Rikudou\Iban\Iban\IbanInterface
or from account number
and bank account (which is then converted to \Rikudou\Iban\Iban\CzechIbanAdapter
object).
See rikudou/iban for description of the interface and classes which let you for example validate the iban and/or the bank account number and bank code.
From IbanInterface implementing classes:
<?php use Rikudou\CzQrPayment\QrPayment; use Rikudou\Iban\Iban\IBAN; use Rikudou\Iban\Iban\CzechIbanAdapter; // initialized with IBAN directly $payment = new QrPayment(new IBAN('CZ5530300000001325090010')); // initialized from Czech account number and bank code $payment = new QrPayment(new CzechIbanAdapter('1325090010', '3030')); // the IBAN classes don't use strict typing so you can also use implicit conversion like this // beware of bank codes that start with zero, those need to always be supplied as a string (like 0300) $payment = new QrPayment(new CzechIbanAdapter(1325090010, 3030));
From account number and bank code directly:
<?php use Rikudou\CzQrPayment\QrPayment; $payment = QrPayment::fromAccountAndBankCode('1325090010', '3030'); // the class does not use strict typing so you can also use implicit conversion like this // beware of bank codes that start with zero, those need to always be supplied as a string (like 0300) $payment = QrPayment::fromAccountAndBankCode(1325090010, 3030);
Setting payment details
There are two approaches to setting payment details. You can set them in an associative array or using the methods provided in the class.
Using associative array
<?php use Rikudou\CzQrPayment\QrPayment; use Rikudou\CzQrPayment\Options\QrPaymentOptions; use Rikudou\Iban\Iban\CzechIbanAdapter; $payment = new QrPayment(new CzechIbanAdapter('1325090010', '3030'), [ QrPaymentOptions::VARIABLE_SYMBOL => 123456, QrPaymentOptions::AMOUNT => 100, QrPaymentOptions::CURRENCY => "CZK", QrPaymentOptions::DUE_DATE => date("Y-m-d", strtotime("+14 days")) ]); // or you can assign the options later via setOptions() $payment->setOptions([ QrPaymentOptions::VARIABLE_SYMBOL => 123456, QrPaymentOptions::AMOUNT => 100, QrPaymentOptions::CURRENCY => "CZK", QrPaymentOptions::DUE_DATE => date("Y-m-d", strtotime("+14 days")), QrPaymentOptions::INSTANT_PAYMENT => true, ]);
Using methods
<?php use Rikudou\CzQrPayment\QrPayment; use Rikudou\Iban\Iban\CzechIbanAdapter; $payment = new QrPayment(new CzechIbanAdapter('1325090010', '3030')); $payment ->setVariableSymbol(123456) ->setAmount(100) ->setCurrency("CZK") ->setDueDate(new DateTimeImmutable('+14 days')) ->setInstantPayment(true);
Exceptions
Description of exceptions thrown:
__construct()
InvalidArgumentException
- if you provide options in constructor and any of those options does not exist\Rikudou\CzQrPayment\Exception\InvalidValueException
- if any of the options contains an asteriskTypeError
- if any of the values is not assignable to the properties after standard php conversions
setOptions()
- same as constructorgetQrString()
\Rikudou\CzQrPayment\Exception\InvalidValueException
- if any of the options contains an asterisk or if the iban is not valid
getQrImage()
\Rikudou\CzQrPayment\Exception\MissingLibraryException
- if the endroid/qr-code library is missing
All of these exceptions (except InvalidArgumentException
and TypeError
) extend the base
\Rikudou\CzQrPayment\Exception\QrPaymentException
.
QR Code image
This library provides many implementations of QR code image using its sister library
rikudou/qr-payment-qr-code-provider. If any supported
QR code generating library is installed, the method getQrCode()
will return an instance of
\Rikudou\QrPaymentQrCodeProvider\QrCode
which can be used to get an image containing the generated QR payment data.
<?php use Rikudou\CzQrPayment\QrPayment; use Endroid\QrCode\QrCode; $payment = new QrPayment(...); $qrCode = $payment->getQrCode(); // get the raw image data and display them in the browser header('Content-Type: image/png'); echo $qrCode->getRawString(); // use in an img html tag echo "<img src='{$qrCode->getDataUri()}'>"; // write to a file $qrCode->writeToFile('/tmp/some-file.png'); // get the raw object from the underlying system $raw = $qrCode->getRawObject(); // let's assume we're using endroid/qr-code v4 assert($raw instanceof QrCode); // do some custom transformations $raw->setLabelFontSize(15); // the object is still referenced by the adapter, meaning we can now render it the same way as before echo "<img src='{$qrCode->getDataUri()}'>";
List of public methods
Constructor
Params
\Rikudou\Iban\Iban\IbanInterface $iban
required - the IBAN for the paymentarray|null $options
- the array with options. The helper classQrPaymentOptions
can be used for options names.
Example
<?php use Rikudou\CzQrPayment\QrPayment; use Rikudou\CzQrPayment\Options\QrPaymentOptions; use Rikudou\Iban\Iban\CzechIbanAdapter; $payment = new QrPayment(new CzechIbanAdapter('1325090010', '3030')); // or with options $payment = new QrPayment(new CzechIbanAdapter('1325090010', '3030'), [ QrPaymentOptions::AMOUNT => 100 ]);
setOptions()
Sets the options, useful if you don't want to set them in constructor.
Params
array $options
required - the same as the constructor param$options
Returns
Returns itself, you can use this method for chaining.
Example
<?php use Rikudou\CzQrPayment\QrPayment; use Rikudou\CzQrPayment\Options\QrPaymentOptions; use Rikudou\Iban\Iban\CzechIbanAdapter; $payment = new QrPayment(new CzechIbanAdapter('1325090010', '3030')); $payment->setOptions([ QrPaymentOptions::AMOUNT => 100 ]);
getIban()
Returns the iban.
Returns
\Rikudou\Iban\Iban\IbanInterface
Example
<?php use Rikudou\CzQrPayment\QrPayment; use Rikudou\Iban\Iban\CzechIbanAdapter; $payment = new QrPayment(new CzechIbanAdapter('1325090010', '3030')); $myIBAN = $payment->getIban();
getQrString()
Returns the string that should be encoded in QR image.
Returns
string
Example
<?php use Rikudou\CzQrPayment\QrPayment; use Rikudou\CzQrPayment\Options\QrPaymentOptions; use Rikudou\Iban\Iban\CzechIbanAdapter; $payment = new QrPayment(new CzechIbanAdapter('1325090010', '3030'), [ QrPaymentOptions::AMOUNT => 100, QrPaymentOptions::VARIABLE_SYMBOL => 1502, QrPaymentOptions::DUE_DATE => new DateTimeImmutable('+14 days'), ]); $qrString = $payment->getQrString(); // SPD*1.0*ACC:CZ5530300000001325090010*AM:100.00*CC:CZK*X-PER:7*X-VS:1502*DT:20210413
static fromAccountAndBankCode()
Returns a new instance of the payment object created from the account and bank code.
Is pretty much an alias to new QrPayment(new CzechIbanAdapter())
.
Params
string $accountNumber
required - The account numberstring $bankCode
required - The bank code
Returns
Returns itself, you can use this method for chaining.
Example
<?php use Rikudou\CzQrPayment\QrPayment; $payment = QrPayment::fromAccountAndBankCode('1325090010', '3030'); // do all the other stuff
getQrImage()
Returns a Qr code via suggested third-party library.
Returns
\Endroid\QrCode\QrCode
Example
<?php use Rikudou\CzQrPayment\QrPayment; use Rikudou\CzQrPayment\Options\QrPaymentOptions; $payment = QrPayment::fromAccountAndBankCode('1325090010', '3030')->setOptions([ QrPaymentOptions::AMOUNT => 100 ]); header('Content-Type: image/png'); echo $payment->getQrImage()->writeString();
Options
This is a list of options you can set.
int $variableSymbol
- the variable symbol, has no defaultint $specificSymbol
- the specific symbol, has no defaultint $constantSymbol
- the constant symbol, has no defaultstring $currency
- ISO 4217 code for currency, defaults toCZK
string $comment
- the payment comment, has no defaultint $repeat
- the number of days that the payment should be repeated if it fails, defaults to7
string $internalId
- internal id of the payment, has no defaultDateTimeInterface dueDate
- the due date for payment, has no defaultfloat $amount
- the amount for the payment, shouldn't have more than 2 decimal places, has no defaultstring $country
- ISO 3166-1 alpha-2 code for country, defaults toCZ
bool $instantPayment
- whether the payment should be made as instant instead of standard payment (depends on bank support)
All of these options can be set using the QrPaymentOptions
helper class as constants for the constructor or
setOptions()
or as methods.
For example, the amount
can be set in an array using the constant QrPaymentOptions::AMOUNT
or using the
method setAmount()
.