Laravel Magento Async Laravel Package

Getting Started

This release (1.3.0) is a compatibility bump — Laravel 13 support — with no API changes called out in the changelog. If you are already on 1.2.x, upgrading is a composer update justbetter/laravel-magento-async away; the real work is confirming your PHP runtime and queue infrastructure meet Laravel 13's baseline before you bump the framework constraint.

Minimal setup path:

1. composer require justbetter/laravel-magento-async and confirm the resolved version is ^1.3.
2. Publish the package assets (php artisan vendor:publish --provider="JustBetter\MagentoAsync\...ServiceProvider") and inspect the config file — this is where the Magento connection, queue names, and any table/model mappings live. Read the published config end to end before touching code; it is the fastest way to understand what the package actually does in your app.
3. Set the Magento credentials/endpoint env vars the config expects, then php artisan config:clear.
4. Run migrations if the package ships any (async tracking tables are common in this family of packages).
5. Start a worker on the package's dedicated queue: php artisan queue:work --queue=magento.

Where to look first: the package's src/ directory for its Jobs and Events classes. In async Magento bridges the jobs are the public contract — their constructor signatures tell you what payload the package expects, which is more reliable than the README for this kind of glue package.

First use case: pick one low-risk entity (typically a product or stock update) and dispatch a single sync job for a known record in php artisan tinker. Watch it land in the queue, watch it succeed, then verify the change in Magento. Do this before wiring anything to model events — it isolates "is my connection configured" from "is my event wiring correct", which are the two failure modes you will otherwise debug simultaneously.

Implementation Patterns

Dispatch from observers/listeners, not controllers. The package's value is decoupling Laravel writes from Magento calls. Hook created/updated/deleted on the models you sync, and dispatch the package's job from there. Controllers stay thin and backfills become trivial.

Use a dedicated queue connection. Magento's API is slow and rate-limited; do not let it share a queue with your mail and webhook jobs. Route the package's jobs to a magento queue with its own worker pool and its own --timeout / --tries. This is the single highest-leverage config decision and it costs you five minutes.

Batch and chunk, don't fan out one job per row. For bulk operations, chunk your Eloquent query and dispatch a job per chunk (or use Bus::batch). One job per SKU across 50k products will drown the worker and hammer Magento. Chunk sizes of 100–500 tend to be the sweet spot, bounded by Magento's request body limits rather than PHP's.

Layer idempotency on top. Async + retries means at-least-once delivery. If Magento's endpoint is a PUT-style upsert keyed on SKU, you are fine. If it appends, you need a dedupe key — a magento_synced_at timestamp or a sync-status column on the source model — so a retried job does not double-write.

Correlate with a reference/UUID. Generate a UUID per sync, put it in the job payload and your logs. When a customer reports a stale price, "find the UUID for SKU X at 14:03" beats grepping job payloads.

Test with Queue::fake() and assert the dispatch, not the HTTP call. The package's job class is the seam. Queue::assertPushed(SyncProduct::class, fn ($job) => $job->sku === 'ABC') gives you fast, reliable tests; reserve real HTTP assertions for an integration suite with a sandbox Magento.

Upgrade path for this release: on Laravel 12 / 1.2.x, run the suite against 1.3.0 first. Since the changelog lists only framework support, treat any failure as framework-related (deprecated container/queue APIs) rather than package-related — and check whether your other Magento packages (API client, etc.) also have Laravel 13-compatible releases, because a staggered upgrade is where this gets painful.

Gotchas and Tips

• Restart workers after every deploy. php artisan queue:restart in your deploy script. Classic silent breakage: new job payload shape, old worker process still holding old code, unserialize failures.
• Config caching in CI. If you cache config during build, changes to Magento credentials in env at runtime will be invisible. Cache on deploy, not in the image, or the queue will quietly talk to staging.
• failed_jobs is your dashboard. Async bridges fail silently by design — the user's save succeeds, Magento never hears about it. Alert on failed-job count and on the queue depth (queue:monitor magento:100). Without this you find out from a customer.
• Timeouts vs. retries. Magento's slowness means a job that times out at 60s may still have succeeded server-side. Set $timeout generously and rely on idempotency rather than tight timeouts plus aggressive retries.
• Rate limits surface as 429s, not exceptions you can fix. Use $backoff with exponential growth ([10, 60, 300]) rather than a flat retry interval.
• Large payloads. Serializing full Eloquent models into a job can exceed the DB queue's payload column or bloat Redis. Pass IDs and re-query in handle(), with the caveat that the row may have changed — snapshot the fields you actually need.
• Check the PHP baseline for Laravel 13 before upgrading. If your production image is on an older 8.x, the composer resolution will fail or, worse, resolve to 1.2.x and you will not notice until a feature is "missing".
• Extension points are typically the config's class bindings (custom job or client class) plus the package's events. Bind your own implementation in a service provider rather than forking — forked glue packages accumulate merge conflicts against minor releases like this one.
• No breaking changes documented in 1.3.0, so pin "justbetter/laravel-magento-async": "^1.3" and let patch releases flow. Re-check the changelog at the 2.x boundary, where the laravel/framework constraint will likely be narrowed again.