Developer notes

Overview · Installation · Configuration · Usage · FAQ

Add-on identity

Item	Value
Add-on ID	kv_advanced_promotions (scheme 3.0, priority 1000)
PHP namespace	Tygh\Addons\KvAdvancedPromotions
Condition keys	kv_ap_schedule, kv_ap_set_amount, kv_ap_customer_usage
Bonus keys	kv_ap_buy_get, kv_ap_tiers, kv_ap_set_discount
Tables	none (rules are stored in ?:promotions.conditions / bonuses)

How it works

• schemas/promotions/schema.post.php adds the conditions and bonuses (zone cart). Their editors are add-on templates used as the picker of each entry (addons/kv_advanced_promotions/editor/*.tpl), so the core condition and bonus rows render them; no core template is overridden. The labels promotion_cond_<key> / promotion_bonus_<key> are written at install from the add-on’s own language variables.
• Conditions are evaluated in pre_promotion_validate (Conditions::check()). In a Multi-Vendor suborder cart (a copy of the calculated parent cart) the condition takes the parent cart’s result; when a suborder is edited later it is evaluated against the parent order, like core conditions.
• Bonuses (Bonuses::apply()) compute a line allocation in integer minor units of the primary currency (Engine): per-unit discounts, largest-remainder splits for totals and caps. Engine::apply() writes floor(D / n) per unit as a core product discount (price, discount, promotions[<id>]['bonuses'][] with a kv_ap entry for the notes) and the remainder to subtotal_discount. The allocation is kept in $cart['kv_ap']['alloc'], which suborders reuse.
• update_promotion_pre normalizes the posted values (Normalizer); vendor lists are dropped in the vendor panel.

Hooks used

Hook	Where (4.17.2 / 4.21.2)	Why
promotion_apply_pre	fn.promotions.php 298 / 298	reset the allocation of a normal cart; license and setting gate
pre_promotion_validate	fn.promotions.php 876 / 889	evaluate the add-on’s conditions
update_promotion_pre	fn.promotions.php 2296 / 2309	normalize condition and bonus values
init_templater_post	fn.init.php (only while an upgrade sync is pending)	Upgrade\Synchronizer
before_dispatch	static handler of License\Client (admin area, console)	license checks and notices

Template hooks: checkout:product_info, block_checkout:product_extra, orders:product_info (storefront and admin/vendor panel), index:styles, index:scripts (admin).

License check

fn_kv_advanced_promotions_is_licensed() (cached License\Client::isActive()) is read in promotion_apply_pre: while the add-on is unlicensed or switched off in its settings, every cart promotion that uses its conditions or bonuses is removed for the request; the bonus and condition code checks again. The promotion editor, settings, order pages and placed orders are not affected. Cron: php admin.php --dispatch=kv_advanced_promotions_license.check.

Full page cache (4.21)

Output appears only on the cart, checkout and order pages, which are not cached. Nothing is written to ?:storage_data at runtime.

File map

app/addons/kv_advanced_promotions/
  addon.xml  init.php  func.php
  controllers/backend/kv_advanced_promotions_license.php
  schemas/promotions/schema.post.php
  Tygh/Addons/KvAdvancedPromotions/{Config,ProductSet,Engine,Normalizer,Bonuses,Conditions}.php
  Tygh/Addons/KvAdvancedPromotions/License/*  Tygh/Addons/KvAdvancedPromotions/Upgrade/Synchronizer.php
design/backend/templates/addons/kv_advanced_promotions/
  editor/{product_set,discount_fields,condition_schedule,condition_set_amount,bonus_buy_get,bonus_tiers,bonus_set_discount}.tpl
  components/{line_notes,line_note}.tpl  hooks/orders/product_info.post.tpl
  hooks/index/{styles,scripts}.post.tpl  hooks/addons/*  license/*
design/backend/css/addons/kv_advanced_promotions/{styles,license}.less
js/addons/kv_advanced_promotions/backend.js
var/themes_repository/responsive/templates/addons/kv_advanced_promotions/
  components/{line_notes,line_note}.tpl  hooks/checkout/product_info.post.tpl
  hooks/block_checkout/product_extra.post.tpl  hooks/orders/product_info.post.tpl  hooks/index/styles.post.tpl
var/themes_repository/responsive/css/addons/kv_advanced_promotions/styles.less
var/langs/en/addons/kv_advanced_promotions.po

Storefront templates and styles ship for the Responsive theme and reach Bright, Nova and other child themes by inheritance.