Events and Subscribers
Overview
In this document, we will learn about the event system in EverShop. EverShop provides a powerful event system that allows you to subscribe to the event and execute your code when the event is triggered.
Events are a way for your application to react to a specific action that occurs. For example, when a product is created, you may want to send an email to the customer. In EverShop, you can subscribe to the product_created event and send an email to the customer.
EverShop core can trigger events at different points in the application and your extensions can subscribe to these events and execute your code asynchronously when the event is triggered.
For example, when a product is created, EverShop core will trigger the product_created event and your extension can subscribe to this event and execute your code.
Emitting Events
And event has a name and a data object. This name is used to identify the event and the data object contains the data that will be passed to the event subscribers.
To emit an event, you can use the event helper function. This function accepts two parameters: the event name and the data object.
import { emitter } from '@evershop/src/lib/event/emitter';
await emitter('product_created', {
product: {
id: 1,
name: 'Product 1'
}
});
Under the hood, an event is stored in the database and the subscribers will be executed asynchronously.
And event will be removed from the pool when all subscribers are executed regardless of the result of the execution.
Subscribe to an Event
To subscribe to an event, the first thing you need to do is create a subscribers folder in your extension directory. This folder will contain all the subscribers for your extension.
├── your-extension
│ ├── subscribers
Next, create a sub folder with the name of the event you want to subscribe to. For example, if you want to subscribe to the product_created event, you need to create a folder with the name product_created.
├── your-extension
│ ├── subscribers
│ │ ├── product_created
Next, create a js file. This file will contain the code that will be executed when the event is triggered. You can have multiple subscribers for the same event.
├── your-extension
│ ├── subscribers
│ │ ├── product_created
│ │ │ ├── sendEmail.js
Here is an example of a subscriber:
module.exports = async function sendMail(data) {
// Send email to the customer
}
This function will be executed asynchronously when the product_created event is triggered. The data object passed to the event will be available in the subscriber function.
The subscriber function must be a default export.
List of Events
A new product created
This event is triggered when a product is created.
// Event name: product_created
// Data object:
{
"product_id": 214,
"uuid": "217fb454-797b-493e-8b33-0daf7c767e1d",
"type": "simple",
"variant_group_id": null,
"visibility": true,
"group_id": 1,
"sku": "new-product",
"price": 120,
"weight": 12,
"tax_class": null,
"status": true,
"created_at": "2024-05-14T02:19:08.371545+00:00",
"updated_at": "2024-05-14T02:19:08.371545+00:00",
"category_id": null
}
// Example subscriber
// module.exports = async function syncData(data) {
// const productSku = data.sku;
// }
A product updated
This event is triggered when a product is updated.
// Event name: product_updated
// Data object:
{
"product_id": 186,
"uuid": "621e5159-0499-4e6a-aeee-13920d818aa9",
"type": "simple",
"variant_group_id": 105,
"visibility": true,
"group_id": 1,
"sku": "NJC44203-Purple-M",
"price": 255,
"weight": 4.9,
"tax_class": null,
"status": true,
"created_at": "2021-10-05T05:47:59+00:00",
"updated_at": "2023-03-11T21:28:25+00:00",
"category_id": null
}
// Example subscriber
// module.exports = async function syncData(data) {
// const productSku = data.sku;
// }
A new category created
This event is triggered when a category is created.
// Event name: category_created
// Data object:
{
"category_id": 18,
"uuid": "d5111391-d1ea-4ea0-9e21-1bfcffe23f48",
"status": true,
"parent_id": null,
"include_in_nav": true,
"position": null,
"created_at": "2022-11-24T14:05:19+00:00",
"updated_at": "2022-11-24T14:05:19+00:00"
}
// Example subscriber
// module.exports = async function syncData(data) {
// const categoryId = data.category_id;
// }
A category updated
This event is triggered when a category is updated.
// Event name: category_updated
// Data object:
{
"category_id": 18,
"uuid": "d5111391-d1ea-4ea0-9e21-1bfcffe23f48",
"status": true,
"parent_id": null,
"include_in_nav": true,
"position": null,
"created_at": "2022-11-24T14:05:19+00:00",
"updated_at": "2022-11-24T14:05:19+00:00"
}
// Example subscriber
// module.exports = async function syncData(data) {
// const categoryId = data.category_id;
// }
An order created
This event is triggered when an order is created.
// Event name: order_created
// Data object:
{
"order_id": 2070,
"uuid": "7afebbbd-69f6-4e2c-84c5-5b899173b867",
"integration_order_id": null,
"sid": "xu8STFfyGfi6IkQcPfZc9rXEgPZ3mjvY",
"order_number": "12070",
"cart_id": 26270,
"currency": "USD",
"customer_id": null,
"customer_email": "admin@admin.com",
"customer_full_name": null,
"user_ip": null,
"user_agent": null,
"coupon": null,
"shipping_fee_excl_tax": 5,
"shipping_fee_incl_tax": 5,
"discount_amount": 0,
"sub_total": 504,
"total_qty": 1,
"total_weight": 6.4,
"tax_amount": 0,
"shipping_note": null,
"grand_total": 509,
"shipping_method": "7d0aba1a-fa8a-4b37-8b0c-5162cb34997e",
"shipping_method_name": "Standard Delivery",
"shipping_address_id": 4141,
"payment_method": "stripe",
"payment_method_name": "Credit Card",
"billing_address_id": 4142,
"shipment_status": "processing",
"payment_status": "pending",
"created_at": "2024-05-08T10:13:00.138845+00:00",
"updated_at": "2024-05-08T10:13:00.138845+00:00",
"sub_total_incl_tax": 504
}
// Example subscriber
// module.exports = async function sendMail(data) {
// const customerEmail = data.customer_email;
// }
An order placed
This event is triggered when a product is placed. This event is triggered by the payment gateway. For example with the offline payment method like COD, this event will be triggered when the order is created. With online payment gateway like Stripe or Paypal, this event will be triggered when the payment is successful.
// Event name: order_placed
// Data object:
{
"order_id": 2070,
"uuid": "7afebbbd-69f6-4e2c-84c5-5b899173b867",
"integration_order_id": null,
"sid": "xu8STFfyGfi6IkQcPfZc9rXEgPZ3mjvY",
"order_number": "12070",
"cart_id": 26270,
"currency": "USD",
"customer_id": null,
"customer_email": "admin@admin.com",
"customer_full_name": null,
"user_ip": null,
"user_agent": null,
"coupon": null,
"shipping_fee_excl_tax": 5,
"shipping_fee_incl_tax": 5,
"discount_amount": 0,
"sub_total": 504,
"total_qty": 1,
"total_weight": 6.4,
"tax_amount": 0,
"shipping_note": null,
"grand_total": 509,
"shipping_method": "7d0aba1a-fa8a-4b37-8b0c-5162cb34997e",
"shipping_method_name": "Standard Delivery",
"shipping_address_id": 4141,
"payment_method": "stripe",
"payment_method_name": "Credit Card",
"billing_address_id": 4142,
"shipment_status": "processing",
"payment_status": "paid",
"created_at": "2024-05-08T10:13:00.138845+00:00",
"updated_at": "2024-05-08T10:13:00.138845+00:00",
"sub_total_incl_tax": 504
}
// Example subscriber
// module.exports = async function sendMail(data) {
// const customerName = data.customer_full_name;
// }
Inventory updated
This event is triggered when the inventory of a product is updated.
// Event name: inventory_updated
// Data object:
{
"old": {
"product_inventory_id": 110,
"product_inventory_product_id": 110,
"qty": 997,
"manage_stock": true,
"stock_availability": true
},
"new": {
"product_inventory_id": 110,
"product_inventory_product_id": 110,
"qty": 996,
"manage_stock": true,
"stock_availability": true
}
}
// Example subscriber
// module.exports = async function syncInventory(data) {
// const productID = data.old.product_inventory_product_id;
// const newStock = data.new.qty;
// }
A new customer created
This event is triggered when a customer is created.
// Event name: customer_registered
// Data object:
{
"customer_id": 12670,
"uuid": "7db52ab1-30a0-4477-9a56-8b681ac31f39",
"status": 1,
"group_id": 1,
"email": "david@evershop.io",
"full_name": "David Nguyen",
"created_at": "2024-05-14T02:11:25.917Z",
"updated_at": "2024-05-14T02:11:25.917Z"
}
// Example subscriber
// module.exports = async function sendWelcomeEmail(data) {
// const customerEmail = data.email;
// }
Support us
EverShop is an open-source project that relies on community support. If you find our project useful, please consider sponsoring us.