marcin-orlowski / bank-qrcode-formatter
Builds source string that can be used to generate valid QrCode matching recommendation of Polish banks
Installs: 2 749
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 3
Forks: 1
Open Issues: 1
Requires
- php: >=5.6.0
- ext-mbstring: *
Requires (Dev)
- phpunit/phpunit: ^5
README
Biblioteka formatująca dane dot. przelewu bankowego pod kątem generowania kodów QR rozpoznawanych przez np. aplikacje mobilne banków operujących na rynku polskim (np. mBank, Inteligo). Wynikiem działania biblioteki jest ciąg znaków (string) sformatowany zgodnie z rekomendacją dot. kodów 2D opublikowaną przez Związek Banków Polskich. Otrzymany ciąg znaków należy użyć do wygenerowania kodu QR, używając do tego dowolnej biblioteki do tego przeznaczonej.
Wymagania
- PHP v5.6+
- Rozszerzenie
mbstring
Instalacja
composer require marcin-orlowski/bank-qrcode-formatter
Przykład użycia
$str = (new \MarcinOrlowski\QrcodeFormatter\Builder()) ->name('Marcin sp. z o.o.') ->bankAccount('01234567890123456789012345') ->title('FV 1234/2020') ->amount(140.50) ->build();
Zwrócony ciąg znaków ($str
) należy następnie użyć z dowolną
biblioteką do generowania kodów QR:
createQrcode($str, '/tmp/qrcode.png');
Bankowe aplikacje mobilne przeprowadzają weryfikacje danych odczytanych z kodu QR, zatem testując niniejszą bibliotekę, należy użyć prawidłowych danych (tj. numer NIP czy numer rachunku bankowego), w przeciwnym razie wygenerowany kod QR zostanie odrzucony przez większość (jeśli nie wszystkie) aplikacje.
API
Utworzenie instancji
public function __construct($type, $strict_mode)
$type
(int
): typ odbiorcy płatności. Dozwolone wartości toBuilder::TYPE_PERSON
(jeśli odbiorcą jest osoba fizyczna) lubBuilder::TYPE_COMPANY
jeśli odbiorcą jest firma. Argument opcjonalny (domyślna wartośćBuilder::TYPE_PERSON
).$strict_mode
(bool
): kontroluje trystrict_mode
(patrzstrict_mode()
). Domyślniefalse
.
Ustawianie parametrów dot. płatności
Metody oznaczone (wymagane) dotyczą ustawiania wymaganych parametrów płatności i muszą zostać wywołane przed wywołaniem
build()
. Wszystkie metody zwracają $this
, co pozwala łączyć ich wywołania łańcuchowo.
public function vatId($vat_id)
: numer podatkowy (NIP) odbiorcy płatności. Podanie NIP-u jest wymagane dla odbiorcy korporacyjnego (TYPE_COMPANY
). dla odbiorców będących osobami fizycznymi podanie NIP nie jest wymagane.$vat_id
(string
|int
|null
): numer podatkowy odbiorcy (8 cyfr). Podanienull
kasuje wprowadzoną wcześniej wartość.
public function bankAccount($account)
(wymagane): docelowy numer rachunku bankowego odbiorcy płatności.$account
(string
) - numer rachunku bankowego (26 cyfr). Dozwolone jest także używanie znaków spacji oddzielających poszczególne cyfry numer lub ich grupy (zostaną one usunięte).
public function name($name)
(wymagane): nazwa odbiorcy płatności.$name
(string
): maksymalna długość to 20 znaków. Widące i zamykające spacje są automatycznie usuwane (trim()
). Jeśli wynikowy ciąg jest dłuższy niż dozwolony, zostanie automatycznie skrócony o ile trybstrict_mode
nie jest aktywny, w przeciwnym razie wystąpiInvalidArgumentException
.
public function country($code)
: dwuliterowy kod kraju odbiorcy płatności.$code
(string
|null
): dwuliterowy kod kraju odbiorcy płatności (np.PL
). Podanienull
kasuje wprowadzoną wcześniej wartość.
public function title($title)
(wymagane): tytuł/opis płatności.$title
(string
): maksymalna długość to 32 znaki. Wiodące i zamykające spacje są automatycznie usuwane. Jeśli wynikowy ciąg jest dłuższy niż dozwolony, zostanie automatycznie skrócony o ile trybstrict_mode
nie jest aktywny, w przeciwnym razie wystąpiInvalidArgumentException
.
public function amount($amount)
(wymagana): kwota płatności wyrażona w groszach (np1000
to10,00 PLN
)$amount
(int
|float
): jeśli podana wartość jest typuint
, uznana jest za wartość wyrażoną w groszach. Gdy podana wartość jest typufloat
, zostanie uznana za wyrażoną w złotych (grosze w części ułamkowej). Przykładowo:(int) 1012
orazfloat 10.12
są tożsame. Minimalna dozwolona wartość to0
która oznacza, iż kwota przelewu musi zostać wprowadzona przez użytkownika w aplikacji bankowej po zeskanowaniu kodu QR.9999999999
dla kwoty podanej jakoint
oraz99999999.99
dla typufloat
. Podanie wartości ujemnej lub przekraczającej maksymalną dozwoloną wartość skutkuje wyjątkiemOutOfRangeException
.
public function reserved1($id)
lubpublic function refId($id)
: zarezerwowane opcjonalne pole, przeznaczone np. na numer referencyjny płatności etc.$id
(string
): ciąg o długości do 20 znaków. Podanie dłuższego ciągu zawsze skutkuje wyjątkiemInvalidArgumentException
.
public function reserved2($id)
: zarezerwowane opcjonalne pole, przeznaczone pierwotnie np. na numer referencyjny usługi Invobill (aka Invoobil, Qlips, QUIK etc).$id
(string
): ciąg o długości do 12 znaków. Podanie dłuższego ciągu zawsze skutkuje wyjątkiemInvalidArgumentException
.
public function reserved3($id)
: zarezerwowane opcjonalne pole$id
(string
): ciąg o długości do 24 znaków. Podanie dłuższego ciągu zawsze skutkuje wyjątkiemInvalidArgumentException
.
Wygenerowanie sformatowanego ciągu
public function build()
: generuje sformatowany ciąg znaków odpowiadający ustawionym parametrom płatności. Zwracana wartość jest typustring
i nie przekracza160
znaków.
Metody dodatkowe
public function strictMode($mode)
: kontroluje działanie trybustrict_mode
. Metody, które automatycznie akceptują i skracają argumenty typu (string
) przekraczające maksymalną dozwoloną długość (np.title()
), działając w trybiestrict_mode
będą zamiast przycinać, przerywały rzucającInvalidArgumentException
.
Licencja
- Written and copyrighted ©2020-2024 by Marcin Orlowski <mail (#) marcinorlowski (.) com>
- Bank-Qrcode-Formatter is open-sourced software licensed under the MIT license