Afterbuy Sdk Symfony Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<laravel-afterbuy-sdk> and publish the config (php artisan vendor:publish --tag=afterbuy-config). The config is where nearly everything interesting lives: credentials, debug_mode, class_map, and the optional validatorBuilder / logger_interface bindings.
• Read the config stub first, then the README endpoint list. The wrapper is thin — the behavioural contract is the Afterbuy XML API itself, and the SDK version pinned in composer.json (wundii/afterbuy-sdk ^1.2.1 as of 1.1.0) determines which API build you are talking to (2.0.467 in this release). Log that pairing somewhere; "which API version are we on?" is a question you will be asked.
• Verify connectivity before writing any integration code. GetVersion (newly documented in 1.1.0) is the cheapest authenticated call in the set — run it from php artisan tinker or a small afterbuy:ping command to prove credentials, network egress and container bindings all work, without touching business data.
• First use case: a scheduled import of orders (or GetUserDefinedFlags if you only need flag metadata) into a local mirror table, with the raw XML response persisted alongside the parsed row. That gets you value on day one and gives you replayable fixtures for everything afterwards.
• Do not skip the two config knobs. class_map defaults to DateTimeInterface: Wundii\AfterbuySdk\Extension\DateTime and controls what type every date field on every response DTO becomes; debug_mode controls whether the SDK dumps request/response traffic. Both change how the package behaves far more than any code you write.

Implementation Patterns

• One service class, one seam. Wrap the SDK client in an AfterbuyService (or AfterbuyGateway) bound in the container, and inject that everywhere. Controllers, jobs and commands never touch the SDK directly. This gives you a single place to stub in tests, a single place to add retry/logging, and it insulates you from container-binding bugs like the validatorBuilder vs logger_interface mix-up fixed in 1.1.0.
• class_map is the extension point — use it instead of post-processing. If your app speaks Carbon, map DateTimeInterface to your own Carbon-backed implementation in config/afterbuy.php rather than walking responses and casting. You get correct types in model casts, diffForHumans(), and JSON serialisation for free. Keep the mapping in config (env-driven if you have several contexts), not in a service provider that mutates the array.
• Gate debug_mode on the environment and never let it reach production. 'debug_mode' => env('AFTERBUY_DEBUG', false) plus a dedicated log channel with short retention. Debug dumps carry full request/response bodies — partner data and possibly credentials. Remember php artisan config:cache after changing it; a cached true survives deploys and quietly fills your disk.
• Treat every call as slow network I/O. Afterbuy is an XML API over the public internet: set job timeouts, use retry() with backoff, and never loop API calls inside a web request. Fetch in chunks in a queued job, upsert into a local mirror keyed on the Afterbuy ID, and let reads hit your own tables.
• Mutating endpoints get their own named methods. CancelOrders (added to the README in 1.1.0) is destructive. Give it an explicit cancelOrders(array $ids): CancelResult method with logging, an audit row and an idempotency check — never route it through a generic "call any endpoint by name" helper, and never wire it to an unconfirmed UI action.
• Idempotent upserts, not inserts. The API will hand you the same order twice (overlapping sync windows, retries, manual re-runs). updateOrCreate on the external ID, and store the raw payload so you can re-map after a package upgrade without re-fetching.
• Fixture-driven tests, especially for 1.1.0. 1.1.0 replaces wundii/structron-based response mapping with the SDK's own, so any test asserting on mapped DTO shapes is exactly the kind of test that catches this. Keep tests/fixtures/afterbuy/ with one recorded response per endpoint you use, including CancelOrders, GetUserDefinedFlags and GetVersion; assert on typed properties (dates, enums, nested DTOs) rather than on raw arrays.
• Smoke-test the container bindings on boot. If you supply a custom validatorBuilder or logger_interface, add a test that resolves the SDK client from the container. The 1.1.0 fix was a container-resolution bug, not a runtime data bug — it only shows up when the binding is actually built.

Gotchas and Tips

• 1.1.0 raises the SDK floor and swaps the mapper. wundii/afterbuy-sdk ^1.2.1 no longer uses wundii/structron for response mapping. If anything in your app extends or type-hints structron classes, or if another dependency pins wundii/structron, resolve the composer conflict before upgrading. After upgrading, re-run the DTO assertions in your fixture suite — types and nullability can shift even when the API version looks compatible.
• The validatorBuilder / logger_interface bug is fixed — drop your workaround. In 1.0.x, a configured validatorBuilder was checked against the logger_interface class, which blew up the container when the logger was configured as a concrete class. If you worked around it by always binding the logger interface (or by not customising the logger at all), you can now bind concrete classes as intended. If you're staying on 1.0.x, keep the workaround.
• class_map changes types, not just formatting. Overriding the default means every date on every DTO is now your class. If you have code doing instanceof Wundii\AfterbuySdk\Extension\DateTime, it will silently stop matching. Prefer type-hinting DateTimeInterface in your own code so the map stays swappable.
• Timezone drift is your problem, not the package's. Afterbuy timestamps come back in the account's local time with no offset. Normalise to UTC on ingest, store UTC, convert at the edges. Do this before you build reporting on top of the mirror table — retrofitting it is miserable.
• Config cache is the #1 source of "it works locally" reports. debug_mode, credentials and class_map all read from cached config. Any deploy that changes config/afterbuy.php or its env vars needs php artisan config:cache (or config:clear in dev). Check bootstrap/cache/config.php before debugging the package itself.
• Re-publish, then diff. A published config file is yours and will not pick up new keys. After upgrading, publish the stub to a temp path and diff it — 1.1.0 added debug_mode and class_map, and future releases will add more. Missing keys usually fall back to sane defaults, but silently, which is worse.
• Credentials stay in env. Never commit them to the published config; the file is checked in and reviewed by people who should not see the Afterbuy account password.
• Error surfaces are noisy. The API returns structured XML faults; unwrap them into a small exception hierarchy (AfterbuyAuthException, AfterbuyValidationException, AfterbuyTransientException) at the gateway boundary so jobs can decide retry-vs-quarantine without string-matching messages.
• GetVersion is the right canary. Put it in a health-check command or a nightly job that alerts on mismatch — it's the earliest signal that Afterbuy shipped an API change ahead of your SDK pin.