README

pure-PHP PAY by square generátor QR kódov

Ľahká, Composer-kompatibilná PHP knižnica na generovanie QR kódov pre slovenský štandard PAY by square.

Prečo táto knižnica?

Väčšina existujúcich PHP knižníc pre PAY by square závisí od externého systémového binárneho súboru xz alebo PECL rozšírení na vykonanie LZMA kompresie, ktorú vyžaduje štandard. To ich robí nekompatibilnými s lacným zdieľaným FTP hostingom, kde sú funkcie na spúšťanie shell príkazov (exec, shell_exec, proc_open) a vlastné C rozšírenia zakázané.

Táto knižnica obsahuje 100% pure-PHP implementáciu LZMA range encodera, takže nevyžaduje žiadne externé binárky ani systémové rozšírenia okrem bežných vlastností PHP jadra.

Vlastnosti

Nulové závislosti od externých binárok (nie sú potrebné nástroje ako xz, 7z a pod.).
Bezpečné pre zdieľaný FTP hosting: Nepoužíva exec, proc_open, FFI ani PECL rozšírenia.
Plynulé (Fluent) API pre platobné údaje (IBAN, BIC, suma, variabilný symbol, konštantný symbol, špecifický symbol, správa pre príjemcu, dátum splatnosti, údaje príjemcu).
Automatické odstraňovanie diakritiky: Automaticky odstraňuje slovenskú diakritiku pre zaistenie kompatibility so staršími bankovými aplikáciami.
Generovanie QR kódov: Priame vykresľovanie do SVG alebo PNG pomocou chillerlan/php-qrcode.

Inštalácia

Pridajte knižnicu do svojho projektu pomocou Composeru:

composer require "hrmpfz/pay-by-square"

Použitie

use Hrmpfz\PayBySquare\Payment;
use Hrmpfz\PayBySquare\PayBySquare;

// 1. Vytvorte a nakonfigurujte platobný príkaz
$payment = Payment::create()
    ->iban('SK0000000000000000000000')
    ->bic('BANKSKBX')
    ->amount('49.00')
    ->currency('EUR')
    ->variableSymbol('202600123')
    ->message('Registracny poplatok')
    ->dueDate(new DateTimeImmutable('2026-07-13'));

// 2. Vygenerujte surový PAY by square payload (formát Base32Hex)
$payload = PayBySquare::encode($payment);
echo "PAY by square retazec: " . $payload . "\n";

// 3. Vykreslite priamo do súborov
// Vykreslenie SVG QR kódu:
PayBySquare::svg($payment, __DIR__ . '/payment.svg');

// Vykreslenie PNG QR kódu (vyžaduje PHP GD rozšírenie):
PayBySquare::png($payment, __DIR__ . '/payment.png');

Nasadenie na zdieľaný FTP hosting

Pre nasadenie knižnice na zdieľaný hosting:

Nainštalujte knižnicu lokálne alebo v CI/CD pipeline pomocou Composeru:
```
composer install --no-dev
```
Nahrajte celý adresár projektu vrátane priečinka vendor/ na váš zdieľaný FTP hosting.
Zavolajte knižnicu vo vašom kóde ako je uvedené vyššie. Nevyžaduje sa žiadna špeciálna konfigurácia ani systémové nastavenia!

Ako to funguje pod kapotou

Štandard PAY by square používa kompresný formát LZMA1 (s parametrami lc=3, lp=0, pb=2). Aby bola knižnica čo najjednoduchšia a vyhla sa portovaniu komplexných LZ77 algoritmov vyhľadávania zhôd z LZMA SDK, táto knižnica implementuje literal-only LZMA range encoder:

Všetky znaky sú kódované ako literálové symboly v rámci LZMA range codera.
Výsledný komprimovaný prúd je len o cca ~14 bajtov väčší než ten komprimovaný s vyhľadávaním zhôd, čo znamená, že typický payload faktúry sa skomprimuje na cca ~105 bajtov.
To je hlboko pod limitom kapacity QR kódu (max 550 znakov) a je 100% kompatibilné so štandardnými dekodérmi používanými slovenskými bankami.

Kredity

Táto knižnica bola kompletne navrhnutá a vygenerovaná pomocou Antigravity, agentického AI asistenta na kódovanie od Google DeepMind.

hrmpfz / pay-by-square

Maintainers

Package info

Statistics

Security