Pcc 3 Deklaracja Bundle Laravel Package

Getting Started

Correct the framing first: this package is not dead. The v5.1.0 release means kch/pcc-3-deklaracja-bundle is on a maintained 5.x line, so the "2017 Symfony bundle you must fork" advice from the previous assessment no longer leads. It is still a Symfony bundle, so a Laravel app gets no service provider, facade, or vendor:publish — but composer require should work on a modern PHP/Symfony stack rather than fighting it.

Read the repo in this order:

1. composer.json — confirm php and symfony/* constraints for the 5.x line. A major version that high implies PHP 8.x support and Symfony 5/6/7, but verify: the release note says nothing about requirements, and we have no repo metadata to cross-check.
2. The declaration version constant. The headline of v5.1.0 is PCC-3(5) v1-0E. Find where that identifier lives (a const, a config parameter, or a FormVersion/SchemaVersion class). That single string decides whether the tax portal accepts your file — it matters more than any other line of code in the package.
3. The generator/builder class — the thing that emits the XML from your inputs.
4. Tests/ fixtures — they will have been updated to the v1-0E shape, which makes them the fastest and most reliable mapping reference (and the diff against the previous tag is your changelog).

First use case: generate a single PCC-3 XML for a straightforward private transaction (car purchase, loan, crypto) and validate it against the PCC-3(5) v1-0E XSD before anyone attempts an upload. Do not batch until one declaration round-trips and is accepted.

Implementation Patterns

Wrap it, don't call it directly from controllers. Bind a thin Pcc3Generator service in a Laravel provider that takes a DeclarationData DTO and returns an XML string. The wrapper costs you one small class and absorbs exactly the kind of churn v5.1.0 represents.

Pin the version and watch for tags. The value of this dependency is now that upstream tracks the ministry's form revisions. Pin an exact tag in composer.json, and let Dependabot/Renovate (or a scheduled composer outdated check) tell you when a new one lands. Treat every bump as a potential output-format change regardless of semver.

Persist the declaration version alongside the data and the XML. Store: the DTO inputs, the generated XML blob, and the declaration-version string the XML was produced for. v5.1.0 silently changes which form version you emit; if you don't record it, you cannot tell which of your stored declarations are now stale or which template produced a rejected file.

Golden-file tests, versioned by directory. Structure fixtures as tests/Fixtures/pcc3/v1-0E/*.xml. An upgrade then means adding a directory and a FormVersion case, not rewriting every assertion. Assert byte-stable output for a given DTO + version.

Validate inside the pipeline, not at the portal. Wire XSD validation against the schema matching your target version into the test suite and into a pre-submit check. This is cheap and catches the failure mode that actually bites.

Regenerate on demand. Keep rendering XML at submit time from stored inputs so you can re-emit an old declaration under a corrected version if the portal's accepted version moves. Queue batch generation one job per declaration, write to object storage, notify on failure.

Gotchas and Tips

• A one-line release note is not a changelog. Dla wersji deklaracji: PCC-3(5) v1-0E ("For declaration version: PCC-3(5) v1-0E") is the entire rationale. There is no breaking-change note, no field-level detail, no semver signal — and minor bumps that retarget a tax form are de facto breaking for anything downstream of the XML. Diff the code between tags (v5.0..v5.1) rather than trusting the notes.
• Form-version mismatch is the number-one rejection cause. The e-Deklaracje portal accepts the currently binding declaration version. Upgrading the package to emit v1-0E while the portal still expects the previous version invalidates every file you generate; failing to upgrade once the ministry mandates v1-0E does the same. Confirm which version your tax office accepts before bumping and re-confirm after.
• Field names, section codes, and rate/code lists change between form versions. Do not assume the v1-0E diff is cosmetic. Re-check each mapped field against the current official schema document and the new fixtures.
• Your stored XML and golden fixtures are now stale. If you were on a 5.0-era release, existing files were generated for the older declaration version — plan a re-validation (and possibly a re-generation) pass over stored declarations, not just a test update.
• Still no Laravel integration. No facade, no config publishing, no vendor:publish. Write the service provider and config yourself; rip out any $this->get('...')/ContainerAwareInterface assumptions if the bundle still carries them.
• Keep the adapter thin, specifically so upgrades are a version bump plus a fixture refresh. If upgrading this package ever means a refactor in your app code, the wrapper is doing too much or too little.
• Don't fork by default anymore. The old "fork → strip Symfony → own it" advice was conditioned on upstream being abandoned. Forking is now the fallback for when the maintainer stops tracking form versions, not the starting plan — staying on releases is what buys you the schema updates.
• PII handling is unchanged and still yours. Declarations carry buyer/seller identification and amounts: encrypt stored inputs, and don't dump full XML into log channels.
• Legal correctness is still yours. Have someone with accounting/tax familiarity sign off on each transaction type's mapping — especially across this form-version boundary, where codes and rates may have shifted.