Listners

Overview of WHAM Customer Listeners

This overview highlights key event listeners that manage customer interactions and account updates. The listeners automate processes such as adding customers to update tables, applying promotions, and handling trade credit requests. They also ensure the security of customer accounts by disabling cards when necessary. Together, these listeners enhance operational efficiency and improve the overall experience for both customers and administrators.

---

The customer module fires the following Listeners.

Class Name	Listener
Toolstation\Customers\Listeners\AddCustomerToUpdatesTable	Updates customer info in CustomerUpdates upon TradeCreditCustomerEnabled event.
Toolstation\Customers\Listeners\AddTradeCreditCustomerAttributes	The AddTradeCreditCustomerAttributes listener updates customer records with trade credit-specific attributes when related events occur.
Toolstation\Customers\Listeners\ApplyNewAccountPromotions	The ApplyNewAccountPromotions listener applies promotional offers to new customer accounts when specific conditions are satisfied.
Toolstation\Customers\Listeners\ApplyNewEmployeePromotions	The ApplyNewEmployeePromotions listener applies promotions to employee accounts linked to customers based on predefined conditions.
Toolstation\Customers\Listeners\DisableCustomerCard	The DisableCustomerCard listener disables a customer's card when they are removed from an account
Toolstation\Customers\Listeners\RequestATradeCreditCard	The RequestATradeCreditCard listener handles trade credit card requests when a specific event is triggered
Toolstation\Customers\Listeners\SendAdminWelcomeEmail	The SendAdminWelcomeEmail listener sends a welcome email to administrators upon the creation of a new customer account

---

AddCustomerToUpdatesTable Listener

The AddCustomerToUpdatesTable class is a listener defined in the Toolstation\Customers\Listeners namespace. This listener is designed to handle the TradeCreditCustomerEnabled event and update the customer information in the CustomerUpdates table. Below is a breakdown of its key elements:

Key Elements:

1. Namespace:

• The class is located within the Toolstation\Customers\Listeners namespace, indicating its relevance to customer-related event handling within the Toolstation application.

2. Event Handling Method:

• The main functionality is encapsulated in the handle method, which accepts an instance of the TradeCreditCustomerEnabled event as a parameter. This method is responsible for processing the event when it is triggered.

3. Customer Retrieval:

• Inside the handle method, the customer associated with the event is retrieved using $event->customer. This allows access to the relevant customer data.

4. CustomerUpdates Model:

• The listener queries the CustomerUpdates table to check if an entry for the customer already exists. If it does, it updates the existing record; if not, it creates a new instance of CustomerUpdates.

5. Setting Attributes:

• The listener sets several attributes on the CustomerUpdates model:
  • setCustomerIdAttribute: Sets the customer ID.
  • setTimestampAttribute: Sets the current timestamp using Carbon.
  • setTypeAttribute: Sets the type of update to 'update'.

6. Saving Changes:

• Finally, the listener saves the updateModel, ensuring that the customer update information is persisted to the database.

Note: This listener is triggered when a trade credit is enabled for a customer, allowing their details to be recorded in the CustomerUpdates table.

---

AddTradeCreditCustomerAttributes Listener

The AddTradeCreditCustomerAttributes class is a listener defined in the Toolstation\Customers\Listeners namespace. This listener is designed to handle events related to trade credit customers and add specific attributes to the customer record. Below is a breakdown of its key elements:

Key Elements:

1. Namespace:

• The class is located within the Toolstation\Customers\Listeners namespace, indicating its relevance to customer-related event handling within the Toolstation application.

2. Queueable Interface:

• The class implements the ShouldQueue interface, which means that the listener's execution will be queued for processing. This allows it to handle events asynchronously, improving the application's performance.

3. Dependency Injection:

• The constructor method accepts a CustomerService instance as a parameter. This service is injected and assigned to a private property, allowing the listener to perform actions related to customer attributes.

4. Event Handling Method:

• The handle method is responsible for processing the event. It accepts the event object, from which it retrieves the associated customer using $event->customer.

5. Attribute Check and Creation:

• The listener checks if the customer already contains the specific attribute (ucn_sst_uid). If it does not exist, it calls the createCustomerAttribute method from the CustomerService to add the attribute. The attributes include:
  • Key: The key for the attribute, fetched using _tsc('customers.attributes.{TS_REGION}.age_checked').
  • Value: Set to 'Trade Credit Enabled'.
  • Date: The current date and time, generated using now().
  • User: The user making the update, fetched using _tsc('customers.account.db_user').

Note: This listener is triggered when a trade credit is enabled for a customer, adding the appropriate attributes to their record if they are not already present.

---

ApplyNewAccountPromotions Listener

The ApplyNewAccountPromotions class is a listener defined in the Toolstation\Customers\Listeners namespace. This listener is designed to apply promotional offers to new customer accounts when certain conditions are met. Below is a breakdown of its key elements:

Key Elements:

1. Namespace:

• The class is located within the Toolstation\Customers\Listeners namespace, indicating its relevance to customer-related event handling within the Toolstation application.

2. Queueable Interface:

• The class implements the ShouldQueue interface, which allows the listener's execution to be queued for processing. This improves performance by enabling asynchronous handling of events.

3. Event Handling Method:

• The handle method is responsible for processing the event. It accepts the event object, from which it retrieves the associated account using $event->account.

4. Current Date and Time:

• A Carbon instance representing the current date and time is created to facilitate comparison with promotion dates.

5. Promotions Retrieval:

• The listener retrieves an array of promotions for new accounts using _tsc('promotions.trade-credit.new-accounts'). This array contains the details of each promotion, including start and end dates.

6. Promotion Application:

• The listener iterates over each promotion in the array. For each promotion:
  • It creates Carbon instances for the start and end dates.
  • It checks if the current date is within the promotion's active period using isAfter and isBefore.
  • If the promotion is active, it calls the Artisan command customers:add-promo-to-account, passing the account ID and the promotion code as parameters.

Note: This listener is triggered when a new customer account is created, applying applicable promotions based on the current date and the promotion validity period.

---

ApplyNewEmployeePromotions Listener

The ApplyNewEmployeePromotions class is a listener defined in the Toolstation\Customers\Listeners namespace. This listener is designed to apply promotional offers to employees added to customer accounts, based on specific conditions. Below is a breakdown of its key elements:

Key Elements:

1. Namespace:

• The class is located within the Toolstation\Customers\Listeners namespace, indicating its relevance to customer-related event handling within the Toolstation application.

2. Event Handling Method:

• The handle method is responsible for processing the TradeCreditEmployeeAddedToAccount event. It accepts the event object as a parameter, from which it retrieves the associated account and customer.

3. Current Date and Time:

• A Carbon instance representing the current date and time is created to facilitate comparisons with promotion dates.

4. Admin Customer Retrieval:

• The listener retrieves the first admin customer associated with the account using $account->adminCustomers->first().

5. Promotions Retrieval:

• The listener retrieves an array of promotions for new accounts using _tsc('promotions.trade-credit.new-accounts'). This array contains details about each promotion, including start and end dates.

6. Promotion Application:

• The listener iterates over each promotion in the array. For each promotion:
  • It creates Carbon instances for the start and end dates.
  • It checks if the promotion code is already associated with the admin customer by accessing the attributes through $adminCustomer->attributes->promoCode($code)->first().
  • If the promotion code exists, it retrieves the start date of the promo code.
  • The listener checks if the current date is within the promotion's active period using isAfter and isBefore.
  • If the promotion is active, it calls the Artisan command customers:add-promo-to-customer, passing the customer ID, promotion code, and promo code start date as parameters.

Note: This listener is triggered when a trade credit employee is added to a customer account, applying any relevant promotions based on the current date and the promotion's validity period.

---

DisableCustomerCard Listener

The DisableCustomerCard class is a listener defined in the Toolstation\Customers\Listeners namespace. This listener is designed to disable a customer's card when they are removed from an account. Below is a breakdown of its key elements:

Key Elements:

1. Namespace:

• The class is located within the Toolstation\Customers\Listeners namespace, indicating its relevance to customer-related event handling within the Toolstation application.

2. Queueable Interface:

• The class implements the ShouldQueue interface, which allows the listener's execution to be queued for processing. This enables asynchronous handling of events, improving overall application performance.

3. Dependency Injection:

• The constructor method accepts a CustomerCardService instance as a parameter, which is injected and assigned to a private property. This service is used to perform actions related to customer cards.

4. Event Handling Method:

• The handle method is responsible for processing the CustomerRemovedFromAccount event. It accepts the event object as a parameter, from which it retrieves the associated customer.

5. Card Disabling Logic:

• The listener first checks if customer cards are enabled by evaluating _tsc('customers.cards.enabled'). If this setting is false, the method returns early without executing further logic.
• If customer cards are enabled, it logs an informational message indicating that the customer's card is being disabled, including the customer ID.

6. Region-Specific Card Disabling:

• The listener uses a match expression to determine the region of the application using _tsc('core.region'). Based on the region, it calls the appropriate method on the CustomerCardService to disable the customer’s card:
  • For 'TSUK', it calls disableTradeCreditCards.
  • For 'TSFR', 'TSNL', and 'TSBE', it calls disableProCardCards.

Note: This listener is triggered when a customer is removed from an account, ensuring that their associated card is disabled as appropriate based on regional settings.

---

RequestATradeCreditCard Listener

The RequestATradeCreditCard class is a listener defined in the Toolstation\Customers\Listeners namespace. This listener is responsible for handling the request for a trade credit card when a specific event is triggered. Below is a breakdown of its key elements:

Key Elements:

1. Namespace:

• The class is located within the Toolstation\Customers\Listeners namespace, indicating its relevance to customer-related event handling within the Toolstation application.

2. Queueable Interface:

• The class implements the ShouldQueue interface, allowing the listener's execution to be queued for processing. This enables asynchronous handling of events, which can enhance the performance of the application.

3. Dependency Injection:

• The constructor method accepts a CustomerCardRequestService instance as a parameter. This service is injected and assigned to a private property, enabling the listener to interact with card request functionalities.

4. Event Handling Method:

• The handle method is responsible for processing the incoming event. It accepts an event object as a parameter, from which it retrieves the associated customer.

5. Trade Credit Card Request:

• Within the handle method, the listener calls the createTradeCreditRequest method of the CustomerCardRequestService, passing the customer associated with the event. This initiates the process of creating a trade credit card request for the specified customer.

Note: This listener is triggered when a request for a trade credit card is made, facilitating the necessary actions to create the request based on the provided customer information.

---

SendAdminWelcomeEmail Listener

The SendAdminWelcomeEmail class is a listener defined in the Toolstation\Customers\Listeners namespace. This listener is responsible for sending a welcome email to administrators when a new customer account is created. Below is a breakdown of its key elements:

Key Elements:

1. Namespace:

• The class is located within the Toolstation\Customers\Listeners namespace, indicating its relevance to customer-related event handling within the Toolstation application.

2. Queueable Interface:

• The class implements the ShouldQueue interface, allowing the listener's execution to be queued for processing. This enables asynchronous handling of events, improving application performance.

3. Event Handling Method:

• The handle method processes the incoming event. It accepts an event object as a parameter, from which it retrieves the associated customer, account, and password token.

4. Email Validation:

• The listener checks if the customer has a valid email by calling hasValidEmail(). If the email is not valid, it logs a warning message and exits the method without sending an email.

5. Logging Information:

• If the email is valid, it logs an informational message indicating that a welcome email is being sent to the customer.

6. Email Sending Logic:

• The listener attempts to send a welcome email using a templated mail class, \Toolstation\Notifications\TemplatedMail\TradeCredit\AdminWelcomeEmail. It passes the customer, account, and password token to the send() method.
• If an exception of type TemplatesException occurs during the sending process, the listener falls back to using the Mail facade to queue a plain AdminWelcomeEmail to be sent instead.

Note: This listener is triggered when a new administrator account is created, ensuring that a welcome email is sent to the customer to facilitate their onboarding process.