formsoft/pity-online-package

Backend PIT-y Online — zasoby formularzy (config JSON + obrazki) i API dla Laravela.

v1.0.7 2026-08-27 13:53 UTC

Requires

• php: ^8.2
• illuminate/http: ^11.0|^12.0|^13.0
• illuminate/routing: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0

Requires (Dev)

• orchestra/testbench: ^9.0|^10.0|^11.0
• phpunit/phpunit: ^11.0|^12.0

proprietary

• Formsoft

Published on Packagist.org on 2026-08-27 13:56 UTC

README

Biblioteka backendowa PIT-y Online dla Laravela 11/12/13.

v1: zasoby formularzy (config JSON + obrazki) oraz API do ich pobierania (+ ping).

Kolejne wersje: certyfikaty, wysyłka do urzędu skarbowego, kolejki.

Instalacja (repozytorium ścieżkowe)

W composer.json aplikacji:

"repositories": [
    { "type": "path", "url": "src/formsoft/pity-online-package", "options": { "symlink": true } }
],
"require": {
    "formsoft/pity-online-package": "@dev"
}

composer update formsoft/pity-online-package

Provider rejestruje się automatycznie (package discovery).

Publikowanie zasobów

php artisan vendor:publish --tag=pity-online-config

Zasoby formularzy (config + obrazki)

Statyczne układy PIT leżą w paczce pod resources/forms/{slug}/v{reportVersion}/. Plik manifest.json mapuje rok podatkowy na właściwą wersję formularza. Dzięki temu ten sam wzór, np. PIT-37 v31, może obowiązywać w wielu latach bez kopiowania configu i obrazków.

resources/forms/
├── manifest.json
├── pit-37/
│   └── v31/
│       ├── config.json
│       └── images/
│           ├── PIT37-01.png
│           └── …
└── pit-o/
    └── v30/
        ├── config.json
        └── images/
            ├── PITO-01.png
            └── …

• config.json — layout pól (może pochodzić z zewnątrz bez edycji)
• images/ — PNG stron formularza
• ścieżki image w JSON (np. /pit37/PIT37-01.png) są rozwiązywane po basename względem images/

Nowy rok podatkowy lub nowa wersja wzoru

1. Dodaj w manifest.json wpis dla nowego roku z reportVersion właściwym dla każdego formularza.
2. Jeżeli wzór się nie zmienił, wskaż istniejącą wersję, np. "reportVersion": "31".
3. Jeżeli wzór się zmienił, dodaj katalog, np. resources/forms/pit-37/v32/, z nowym config.json i PNG, a następnie wskaż wersję 32 w manifeście.
4. Wypuść nową wersję paczki (semver).

Konfiguracja

Klucz / env	Opis
pity-online.default_tax_year / PITY_ONLINE_DEFAULT_TAX_YEAR	Domyślny rok, gdy klient nie poda ?year=
pity-online.assets.path / PITY_ONLINE_FORMS_PATH	Nadpisanie katalogu formularzy (null = resources/forms w paczce)
pity-online.assets.cache_control / PITY_ONLINE_ASSETS_CACHE	Nagłówek Cache-Control dla PNG (domyślnie public, max-age=86400)

API

Prefiks domyślny: api/pity-online (PITY_ONLINE_ROUTE_PREFIX).

# Health check
curl -s "http://localhost/api/pity-online/ping"

# Lata podatkowe dostępne w manifeście
curl -s "http://localhost/api/pity-online/years"

# Lista formularzy na rok
curl -s "http://localhost/api/pity-online/forms?year=2025"

# Config layoutu (URL-e obrazków przepisane na endpointy paczki)
curl -s "http://localhost/api/pity-online/forms/PIT-37/config?year=2025"

# Obrazek strony
curl -s -o PIT37-01.png "http://localhost/api/pity-online/forms/PIT-37/images/PIT37-01.png?year=2025"

Akceptowane aliasy typu formularza: PIT-37, pit-37, pit37 (analogicznie PIT-O / pit-o / pito).

Struktura

config/pity-online.php              konfiguracja (routing, assets, default_tax_year)
resources/forms/manifest.json       mapowanie roku podatkowego na wersję wzoru
resources/forms/{form}/v{version}/  config.json + images/*.png
routes/api.php                      trasy paczki
src/Contracts/                      interfejsy (punkty podmiany w kontenerze)
src/Http/Controllers/               kontrolery API
src/Http/Resources/                 transformacja odpowiedzi API
src/Providers/                      service provider
src/Repositories/                   implementacje kontraktów
src/Services/                       warstwa aplikacyjna
tests/                              testy (Orchestra Testbench)

Testy

cd src/formsoft/pity-online-package
composer install
composer test