Szamlazzhu Laravel Package

Product Decisions This Supports

• Build vs. buy for invoicing: This package is the maintained Laravel bridge to the official szamlazz.hu SDK. Invoicing is compliance-critical and non-differentiating, so the default decision should be to consume the vendor SDK through this wrapper rather than build or fork issuance logic. v3.0.0 tracking SDK 2.12.3 → 2.12.5 is evidence the wrapper stays close to the vendor surface, which reduces the long-term cost of ownership.
• Platform upgrade sequencing: Requiring Laravel 12/13 (PHP 8.3+ unchanged) makes the framework upgrade a hard dependency for invoicing. This turns "upgrade Laravel" from an engineering hygiene item into a release-planning constraint for any roadmap work that touches billing, checkout, or account management.
• Feature scope for simplified invoice content: InvoiceHeader::setSimpleItems() (SDK 2.12.4) exposes simplified line items on the invoice image. This supports product decisions around lightweight invoice presentation for consumer-facing or low-detail invoices, and the pre-flight ValidationException on delivery notes and corrective invoices means we can surface clear, catchable failures in the UI instead of failing at the API boundary.
• Tax/VAT roadmap with a known deadline: setProfitVat() (arresAfa) and setPriceGapVatBase() (arresAfaAlap) still work but are removed after 2027-02-15, with PHP 8.4+ emitting deprecation notices. This is a dated roadmap item — any pricing, margin, or VAT-base logic built on these fields needs a migration plan well before that date, and the deprecation noise on PHP 8.4+ is a signal to schedule it rather than defer it.
• Operational error-handling contract: Non-JSON responses now raise ResponseException instead of a PHP TypeError. That makes failure modes catchable and classifiable, which supports decisions about retry policy, alerting, and whether invoice failures should block a checkout flow or degrade gracefully.
• Deployment and environment hygiene: Publishing config and the sessions migration under a single --tag=szamlazzhu, with a fresh timestamp and a working down(), makes the package's install/rollback story predictable — relevant to decisions about environment provisioning and whether invoicing setup can be part of standard onboarding.

When to Consider This Package

Adopt when:

• You are on Laravel 12 or 13 with PHP 8.3+, and you invoice through szamlazz.hu (typically Hungarian-market billing, where e-invoicing compliance is mandatory rather than optional).
• You want the official SDK's behavior without maintaining your own HTTP/serialization layer — the JSON/ResponseException fix and the pre-send validation on delivery notes and corrective invoices both reduce custom defensive code you'd otherwise write.
• You need the vendor's newer invoice-content capabilities, specifically simplified items on the invoice image, and you're willing to validate those constraints before submission.
• You value a managed publish story: one tag for config plus migration, with a reversible down().

Look elsewhere or wait when:

• You are on Laravel 10 or 11. Do not force this upgrade; stay on ^2.0 until the framework upgrade is scheduled. Adopting v3.0.0 prematurely couples an invoicing change to a platform migration and doubles the blast radius.
• You need a provider-agnostic billing abstraction. This package is a direct szamlazz.hu wrapper; it is not a multi-provider invoicing layer.
• Your VAT logic depends on arresAfa / arresAfaAlap and you can't schedule remediation before 2027-02-15. You can adopt, but treat the deprecation as an accepted, dated liability with an owner.
• You extend package classes and override constants. Typed class constants mean your overrides must carry matching types; that's a small but real refactor cost to scope before upgrading.
• You rely on the cached session in the database driver. The cache key moves from md5 to sha256; the upgrade is safe but leaves orphaned rows in the sessions table that should be cleaned up as part of the rollout.

How to Pitch It (Stakeholders)

For executives: This is a routine, vendor-aligned update to our Hungarian invoicing integration, not a strategic change. It keeps us on the officially supported SDK, adds a small invoice-presentation capability, and improves how failures are reported. The main cost is timing: the new version requires Laravel 12/13, so it should ride along with our planned framework upgrade rather than trigger one. There is one dated item to note — two VAT-related fields are deprecated by the vendor with removal after February 2027, giving us ample runway to migrate with no customer-facing impact expected.

For engineering: v3.0.0 is a breaking release with a clean, bounded upgrade path. Three changes matter: (1) Laravel 10/11 support is dropped in favor of 12/13 — gate this behind the framework upgrade, or pin ^2.0; (2) class constants are now typed, so any subclass overriding a package constant needs matching types; (3) the session cache key switches from md5 to sha256 — no action required, but database-driver deployments should prune stale session rows. On the positive side, setSimpleItems() lands with pre-send validation for delivery notes and corrective invoices, config plus migration publish under a single tag with a proper down(), and malformed responses now throw ResponseException rather than TypeError, which gives us a catchable error contract for retries and alerting. Budget a small, well-understood refactor and schedule the arresAfa/arresAfaAlap migration before the vendor's 2027-02-15 removal.