PromotionService
in package
Service for resolving active promotions and calculating sale prices.
Handles precedence logic: item-scope beats category-scope beats store-wide at equal priority. Higher priority number always wins.
Tags
Table of Contents
Properties
- $cache : array<string|int, mixed>
- $promotionModel : Promotion
Methods
- __construct() : mixed
- Initialize the promotion service.
- applyToMenuItems() : array<string|int, mixed>
- Enrich an array of menu items with sale pricing info.
- clearCache() : void
- Clear the request-level cache (for testing).
- getActivePromotions() : array<string|int, mixed>
- Get all active promotions with their targets for a business (cached per request).
- getSalePrice() : array<string|int, mixed>
- Get the sale price info for a menu item.
- getSalePriceForVariant() : array<string|int, mixed>
- Get the sale price info for a variant.
- calculateDiscountedPrice() : float
- Calculate the discounted price given a base price and promotion.
- findBestPromotion() : array<string|int, mixed>|null
- Find the best (highest priority, then largest discount) promotion for an item.
Properties
$cache
private
static array<string|int, mixed>
$cache
= []
Request-level cache keyed by business ID
$promotionModel
private
Promotion
$promotionModel
Promotion model
Methods
__construct()
Initialize the promotion service.
public
__construct() : mixed
applyToMenuItems()
Enrich an array of menu items with sale pricing info.
public
applyToMenuItems(int $businessId, array<string|int, mixed> $items) : array<string|int, mixed>
Adds 'on_sale', 'original_price', 'sale_price', 'promotion_id', 'badge' keys to each item in the array.
Parameters
- $businessId : int
-
Business ID
- $items : array<string|int, mixed>
-
Array of menu item records
Return values
array<string|int, mixed> —Enriched items
clearCache()
Clear the request-level cache (for testing).
public
static clearCache() : void
getActivePromotions()
Get all active promotions with their targets for a business (cached per request).
public
getActivePromotions(int $businessId) : array<string|int, mixed>
Returns a structured array with promotions indexed by ID, plus lookup maps for quick item/category resolution.
Parameters
- $businessId : int
-
Business ID
Return values
array<string|int, mixed> —['promotions' => [...], 'item_map' => [...], 'category_map' => [...], 'store_wide' => [...]]
getSalePrice()
Get the sale price info for a menu item.
public
getSalePrice(int $businessId, array<string|int, mixed> $item) : array<string|int, mixed>
Parameters
- $businessId : int
-
Business ID
- $item : array<string|int, mixed>
-
Menu item record (must have 'id', 'price', 'category_id')
Return values
array<string|int, mixed> —['on_sale' => bool, 'original_price' => float, 'sale_price' => float, 'promotion' => array|null, 'badge' => string|null]
getSalePriceForVariant()
Get the sale price info for a variant.
public
getSalePriceForVariant(int $businessId, array<string|int, mixed> $item, array<string|int, mixed> $variant) : array<string|int, mixed>
Parameters
- $businessId : int
-
Business ID
- $item : array<string|int, mixed>
-
Menu item record
- $variant : array<string|int, mixed>
-
Variant record (must have 'price')
Return values
array<string|int, mixed> —Same structure as getSalePrice()
calculateDiscountedPrice()
Calculate the discounted price given a base price and promotion.
private
calculateDiscountedPrice(float $price, array<string|int, mixed> $promotion) : float
Parameters
- $price : float
-
Original price
- $promotion : array<string|int, mixed>
-
Promotion record
Return values
float —Discounted price (never below 0)
findBestPromotion()
Find the best (highest priority, then largest discount) promotion for an item.
private
findBestPromotion(array<string|int, mixed> $active, int $itemId, int $categoryId) : array<string|int, mixed>|null
Precedence at equal priority: item-scope > category-scope > store-wide.
Parameters
- $active : array<string|int, mixed>
-
Active promotions data from getActivePromotions()
- $itemId : int
-
Menu item ID
- $categoryId : int
-
Category ID
Return values
array<string|int, mixed>|null —Best promotion record or null