Szamlazzhu Laravel Package

Technical Evaluation

Package context. This is the Laravel wrapper around the official szamlazz.hu PHP SDK, i.e. it sits on the invoicing path — a regulated, customer-visible, financial-record workflow. That drives the risk posture below: we treat v3.0.0 as a controlled upgrade, not a routine dependency bump.

Architecture fit. Low architectural impact, high coupling impact. The package is a thin adapter (config + service provider + typed request/response objects over the vendor SDK), so it does not change our application architecture. The coupling is to (a) the Laravel major version and (b) the vendor SDK contract. v3.0.0 moves both: it consumes SDK v2.12.5 and raises the floor to Laravel 12/13. No prior assessment exists, so this release is also our baseline record for the package.

Integration feasibility. Feasible and well-signposted. The breaking changes are narrow and each ships with an explicit action ("stay on ^2.0", "type your overridden constants", "delete stale session rows"). The two genuinely new capabilities are operational rather than functional: vendor:publish --tag=szamlazzhu now emits config and the sessions migration together (with a fresh timestamp and a down()), and InvoiceHeader::setSimpleItems() exposes simpleItems. There is exactly one behavioural fix that matters to us: non-JSON responses now throw ResponseException instead of a PHP TypeError, which is a net win for error handling but a change in exception type on a failure path.

Technical risk (ranked).

1. Laravel 12/13 floor. Any application on Laravel 10/11 is pinned to ^2.0 and will silently stop receiving fixes. We have no inventory of the current Laravel versions across our services — this is the single largest unknown.
2. Session cache re-key (md5 → sha256). The first request after deploy opens a new szamlazz.hu session. With the database session driver, old rows linger in the sessions table. Concurrent first requests (multi-instance rollout) may each open a session — harmless for correctness, but it is a deploy-window behaviour we should expect and monitor rather than diagnose live.
3. Deprecations with a hard date. InvoiceHeader::setProfitVat() (arresAfa) and Item::setPriceGapVatBase() (arresAfaAlap) are removed by the official SDK after 2027-02-15. They still work; on PHP 8.4+ they emit deprecation notices. This is tax/VAT semantics — if we use them, the removal is a specification change, not a code change.
4. Typed class constants. Only bites if we subclass package classes and override constants; a compile-time failure, therefore cheap to detect but easy to miss in untested subclasses.
5. Migration republish on an already-migrated database. Publishing with a fresh timestamp onto an environment that already has the v2 sessions migration risks a duplicate create-table migration. Must be verified per environment before running migrate.
6. Tooling rebuild on the laravel package skeleton. Service provider, config shape and publish tags may have moved. Low severity, but it invalidates any local patches or forks.

Key questions (need answers before we commit a plan).

• Which of our services use this package, and on which Laravel major? (Blocker for sequencing.)
• Do we extend any package class or override its constants?
• Do we call setProfitVat() / setPriceGapVatBase() today? If yes, who owns the VAT-specification replacement and by when?
• Which session driver do we run? If database, who owns the cleanup of pre-upgrade rows, and is migrate gated in the release process?
• Do we catch the old TypeError on response conversion anywhere, and does monitoring alert on exception type?
• Is setSimpleItems() a requirement we have, or a capability we are simply inheriting?

Integration Approach

Stack fit. Requires Laravel 12 or 13; PHP 8.3+ is unchanged from prior releases, so PHP is not the constraint — Laravel is. We should confirm our Laravel upgrade path is already funded, because this package now rides on it rather than the reverse.

Migration path.

• Laravel 12/13 services: upgrade package ^2.0 → ^3.0 in a dedicated PR with no unrelated changes.
• Laravel 10/11 services: stay on ^2.0 and record an explicit exception with an owner and target date. Do not attempt to hold v3 on an old Laravel.
• All services: publish/config review, constant-override check, session-driver check, exception-handling check.

Compatibility checks (gate list).

1. composer why-not / lockfile audit for Laravel constraints.
2. Static search for subclasses of package classes with const overrides → add matching types.
3. Static search for setProfitVat, setPriceGapVatBase, arresAfa, arresAfaAlap → inventory and owner.
4. Search for TypeError handling around invoice responses → migrate to ResponseException.
5. Diff the published config against our current config/szamlazzhu.php before accepting the new publish output.
6. Confirm whether the sessions migration already exists in each environment's migrations table.

Sequencing.

1. Inventory and answer the key questions (no code).
2. Upgrade the first Laravel 12/13 service in a non-production environment; run a full invoice-issue, delivery-note and corrective-invoice path (the latter two now validate for simpleItems and throw before the request — good for staging verification, and worth a negative test).
3. Ship to a single low-volume production service; observe for one invoicing cycle.
4. Clean up pre-upgrade session rows (database driver) as a scheduled, reviewed task — not as part of the deploy.
5. Roll out to remaining v3-eligible services.
6. Open a separate, longer-running workstream for the 2027-02-15 VAT-attribute removal; do not bundle it here.

Rollback. Package rollback is a lockfile revert. Note the asymmetry: the session re-key means a rollback re-opens sessions in the opposite direction, and the duplicated-migration risk means rollback must include migrate:rollback of the newly published migration where applicable. Document this rather than assume a clean git revert.

Operational Impact

Maintenance. Net neutral-to-positive. Being rebuilt on the laravel package skeleton lowers our cost to reason about the codebase, and consuming SDK v2.12.5 keeps us current with the vendor. The cost we take on is the Laravel 12/13 floor, which converts a package upgrade into a platform upgrade for lagging services.

Support. Two support obligations are created:

• An internal deprecation tracker for arresAfa / arresAfaAlap with a hard date of 2027-02-15 and a named owner.
• A version-pinning policy: Laravel 10/11 services on ^2.0 are explicitly frozen and must not be presented as "supported" in any roadmap without an upgrade date attached.

Scaling. No throughput or payload implications. The one scaling-adjacent change is the session cache re-key, which is a one-time per-key event; the only thing that scales with it is deploy concurrency (multiple instances opening sessions simultaneously on the first post-deploy request).

Failure modes to watch.

• Silent version drift: a service stuck on ^2.0 stops receiving SDK parity fixes with no visible failure.
• Deploy-window invoice errors: first-request session recreation coincides with the least-tested moment of the release.
• Duplicate migration: new-timestamp publish on an already-migrated database.
• Exception-type change: downstream handlers written for TypeError will no longer match, so a malformed gateway response surfaces differently — better, but different.
• Validation-before-send: delivery notes and corrective invoices combined with setSimpleItems() now fail fast with ValidationException; anything that "worked" by sending and tolerating a gateway error will now surface earlier and louder.
• PHP 8.4 deprecation noise if we are on 8.4+: log volume and alert fatigue from the two deprecated setters.

Ramp-up. Low for engineers — the API surface is unchanged apart from one new setter, and the typed-constant rule is mechanical. The real ramp-up is organisational: getting the Laravel version inventory, agreeing who owns the VAT deprecation, and adding the migration/publish step to the release checklist. Estimate roughly a day of engineering per service for the v3 upgrade itself, with the Laravel upgrade as the dominant, separately-estimated cost.

Recommendation. Adopt v3.0.0 on Laravel 12/13 services, hold Laravel 10/11 services on ^2.0 with a dated exception, and treat the arresAfa deprecation as a tracked compliance item with an owner — not a footnote in a changelog.