Szamlazzhu Laravel Package

Getting Started

• Requirements: Laravel 12 or 13 and PHP 8.3+. If you are still on Laravel 10/11, stay on the package’s ^2.0 line or upgrade Laravel first. v3.0.0 will not install on older Laravel versions.
• Install and publish: Require the package via Composer, then run php artisan vendor:publish --tag=szamlazzhu. This publishes both the config file and the sessions migration in one step. The migration gets a fresh timestamp and includes a down() method.
• Configure: Open the published config (typically config/szamlazzhu.php) and set your szamlazz.hu API key and any environment-specific options. Review the package README for the exact config keys.
• First use case: Build an InvoiceHeader, attach one or more Item instances, and send the invoice through the package’s client. Use InvoiceHeader::setSimpleItems() when you want simplified items to appear on the invoice image.

Implementation Patterns

• Daily invoice creation: Resolve the package client from Laravel’s container (or use the provided facade if available), construct an InvoiceHeader, add items, set buyer/seller data, then call the create-invoice method. Keep invoice construction in a dedicated service or action class so it is testable and reusable.
• Simplified invoice image items: Use InvoiceHeader::setSimpleItems() for the simpleItems field introduced from SDK 2.12.4. This is useful when the printed/PDF invoice image should show a simplified item list. It throws ValidationException for delivery notes and corrective invoices before any request is sent, so validate the invoice type first or catch the exception and return a clear domain error.
• Session caching: The package caches the szamlazz.hu session keyed by the SHA-256 hash of the API key. No code changes are needed after upgrading; the first request opens a new session. If you use the database session driver, old MD5-keyed rows remain in the sessions table and can be cleaned up separately.
• Database session storage: If your app uses the database session driver and you rely on the package’s cached session, publish and run the migration. Because config and migration are published together under the szamlazzhu tag, keep them in sync when upgrading.
• Error handling: Catch ResponseException for responses that cannot be converted to JSON. This replaces the previous PHP TypeError, so update any catch blocks or exception handlers that expected TypeError.
• Extending package classes: If you subclass a package class and override a class constant, match the new typed constant declaration, e.g. public const string SYSTEM_DOWN.
• Deprecation planning: Avoid InvoiceHeader::setProfitVat() (arresAfa) and Item::setPriceGapVatBase() (arresAfaAlap) in new code. They still work, but the upstream SDK removes them after 2027-02-15, and calling them on PHP 8.4+ triggers a deprecation notice.

Gotchas and Tips

• Laravel version constraint: The most likely upgrade blocker is Laravel 10/11. Check composer.json before upgrading; if you cannot move to Laravel 12/13 yet, pin ^2.0.
• Typed constants: PHP 8.3+ typed class constants are now used throughout the package. Overriding a constant without the same type will cause a fatal error. Add the type when overriding.
• Session cache key change: The switch from MD5 to SHA-256 is transparent, but with the database session driver the old rows are not removed automatically. Clean up stale sessions if they matter for storage or privacy.
• setSimpleItems() restrictions: Delivery notes and corrective invoices throw ValidationException before the API call. Do not assume every invoice type accepts simplified items; gate the call by invoice type or handle the exception explicitly.
• Deprecated VAT methods: They still function, but PHP 8.4+ deprecation notices can pollute logs and break strict error handlers. Treat them as migration work, not as immediate breakage.
• Non-JSON responses: The new ResponseException is more accurate than the old TypeError. Make sure your exception handler catches ResponseException so API outages or HTML error pages surface as domain errors.
• Publishing behavior: The szamlazzhu tag publishes both config and migration. If you have customised the config, review the published file before overwriting. The migration’s fresh timestamp and down() method make rollbacks safer.
• Debugging: When an invoice fails, check the published config first, then inspect the exception type: ValidationException usually means invalid invoice data or an unsupported invoice type/feature combination; ResponseException usually means the remote API returned something non-JSON. Log the request context around the package call to distinguish local validation from remote failures.
• Extension points: Prefer composing services around the package over subclassing its internals. If you must extend, pay attention to typed constants and deprecated methods so your subclass remains compatible with the next SDK port.