Back In Stock Statamic Laravel Package

Getting Started

• Install the package and publish its config/migrations, then run php artisan migrate. The v1.0.1 release adds a new column to back_in_stock_items, so existing installs must migrate as part of the deploy — do not skip this in CI/CD.
• First place to look: the back_in_stock_items table and the package’s notification/restock service. That table is the source of truth for who is waiting, what they asked for, and which restock batch they belong to.
• First use case: an out-of-stock product page with a “Notify me when back in stock” form. Submit the form, send the confirmation email, and let the package resolve the waiting list when stock rises.
• Configure the restock mode early. “Everyone waiting” is the simple broadcast model; “As many as came back” is the inventory-aware model for limited stock. Pick per product or globally depending on your catalogue.
• Run php artisan migrate locally, then submit a request against a product with zero stock and raise the stock in the Control Panel or via your own inventory update. That is the fastest end-to-end smoke test.

Implementation Patterns

• Double opt-in flow: Treat the initial form submission as a request, not a subscription. The package sends a confirmation email, and only confirmed requests should be eligible for restock emails. This is also where the v1.0.1 “one email per address” behaviour matters — concurrent form submissions for the same address and product should collapse into one request and one confirmation.
• Restock triggering: Hook restock resolution into the same path that changes product stock, or rely on the package’s model events. The release notes confirm that without a queue, sending starts after the product save has completed, so stock updates during a send do not block the save.
• Choosing the restock strategy:
  • Use “Everyone waiting” when stock is effectively unlimited or you are restocking a large batch and want to notify all confirmed waiters.
  • Use “As many as came back” for limited inventory. The v1.0.1 fix means the count is based on units sold during the wait, not the raw number of requests. If 5 people ask and 3 units sell before the emails go, only 2 people are emailed. Design your expectations around that — it is not a simple FIFO queue of all requesters.
• Confirmation while in stock: The documented behaviour is that confirming a request while the product is already in stock sends the next email immediately — to everyone for “Everyone waiting”, or to the longest waiter for “As many as came back”. Test this path explicitly because it bypasses the normal stock-rise trigger.
• Queue vs sync: If your app uses queues, ensure the package’s notifications are dispatched on the right queue and that stock changes during a send do not lose pending emails. The release notes specifically call out that emails lined up while others are sending are no longer lost. If you do not use a queue, rely on the after-save send behaviour rather than trying to send inside the stock update transaction.
• Control Panel integration: The list now loads each product’s last restock in one query, so it is safe to surface last-restock information in admin listings. Avoid adding your own per-row queries for the same data.
• Retention and cleanup: Restock history is kept for a year after the last request for a product is deleted. If you build reporting or admin views, query the history with that retention window in mind, and do not assume history disappears as soon as requests are removed.
• Testing: Use Notification::fake() and Queue::fake() to assert confirmation and restock notifications. Write feature tests for the two restock modes, the confirmation-while-in-stock path, and the duplicate-address race. Since “one email per address” is now guaranteed at the package level, assert that two near-simultaneous submissions produce one request and one confirmation.

Gotchas and Tips

• The new migration is mandatory. v1.0.1 adds a column to back_in_stock_items. Deployments that run code before migrations will break or silently misbehave. Put php artisan migrate in the release step and verify it in staging.
• “As many as came back” is not “first N requesters”. It is inventory-aware: units sold during the wait reduce the number of people emailed. If you need strict FIFO, this mode may surprise you. The release notes explicitly say “what’s lined up never goes over the stock”.
• Race conditions around confirmation and restock: The package now handles emails queued while others are sending, and collapses duplicate requests per address. Do not add your own deduplication layer on top unless you have a specific reason — it can mask the package’s behaviour and make debugging harder.
• Stock changes during a send: Without a queue, sending starts after the product save has finished, so saves during a send do not wait. With a queue, ensure workers are running and that the notification job reads current stock rather than a stale snapshot.
• Confirmation-while-in-stock is easy to miss in tests. If a product is already in stock when a user confirms, the package sends the next email immediately. That can look like a duplicate if your UI also triggers a restock check. Let the package own that path.
• Retention is one year after the last request is deleted, not one year after the restock. If you build admin reporting, do not assume history vanishes when the product’s waiting list is cleared. Conversely, if you need long-term analytics, export it — the package is not an audit log.
• Control Panel query behaviour changed. The list now loads last restock in one query. If you had worked around N+1 issues with custom eager loading or caching, revisit that code — it may now be redundant.
• SVG metadata removal is cosmetic but relevant if you diff assets. Brand SVGs no longer carry embedded metadata. If your build pipeline or tests hash those files, expect changed hashes.
• Extension points: The package’s notification classes and restock strategy are the natural places to customise email content or eligibility. Prefer overriding notifications and config over forking the restock logic, especially around the “as many as came back” calculation, which is subtle and was just fixed.
• Debugging tip: When a restock email does not arrive, check in this order: confirmed request exists, product stock actually rose above the threshold, restock mode matches expectations, notification was dispatched, and the address is not a duplicate. The v1.0.1 fixes target the middle steps, not delivery infrastructure.