Developer notes

Overview · Installation · Configuration · Usage · FAQ

Data model

Table	Columns	Notes
?:kv_sep_methods	shipping_id PK, transit_min, transit_max	Transit days per shipping method (-1 = not set). Written from the shipping method page.
?:kv_sep_products	product_id PK, handling_days	Handling time per product. Written from the product page.
?:kv_sep_companies	company_id PK, handling_days, cutoff_time	Multi-Vendor vendor values (-1 / empty = store value). Written from the vendor profile.

Rows are removed with their shipping method, product or company. All tables are dropped on uninstall.

Storefront endpoints (kv_shipping_estimator_product.*, AJAX GET only, never cached by the full page cache)

Mode	Parameters	Returns
estimate	product_id, amount, product_options[<option_id>], optional loc[country|state|zipcode|city], result_ids=kv_sep_<product_id>	The estimate fragment (views/kv_shipping_estimator_product/estimate.tpl). Location: loc > cookie kv_sep_loc > cart address > profile > store default.
form	product_id, result_ids=kv_sep_form_<product_id>	The change-location form.
states	country	JSON kv_sep_states: [{code, name}].

Non-AJAX requests and POST get 404. Without a valid license or with the add-on switched off, all modes are closed.

The cookie kv_sep_loc (country|state|zipcode|city, URL-encoded parts, 180 days, SameSite=Lax) is written by the storefront script only; the server never sets cookies or session data on GET.

Calculation

Estimator::calculate() builds a virtual cart (products[cart_id] = product_id, amount, product_options, extra, price, plus kv_sep_virtual) and calls fn_calculate_cart_content($cart, $auth, 'A', true, 'F', true, CART_LANGUAGE, 'C'), the same call as the core checkout.shipping_estimation. It does not use fn_add_product_to_cart() (product popularity, session writes, add-to-cart hooks). Notifications raised by the core during the calculation are removed again.

Hooks (identical arguments in 4.17.2 and 4.21.2)

Hook	Use
calculate_cart_content_before_shipping_calculation	Renames the core shipping rate cache key (calculated_shipping_rates → kv_sep_rates) for the virtual cart, so the visitor’s checkout rate cache is never overwritten.
shippings_get_shippings_list_post	Drops realtime methods from the virtual cart when “Include realtime carrier rates” is off.
update_shipping_post, delete_shipping	Transit days of shipping methods (shipping_data[kv_sep][transit_min|transit_max]).
update_product_post, delete_product_post	Handling time of products (product_data[kv_sep_handling_days]).
update_company, delete_company	Vendor handling time and cut-off (company_data[kv_sep][handling_days|cutoff_time], Multi-Vendor).

Template hooks: storefront products:product_detail_bottom (post, placeholder); admin shippings:update, products:update_product_amount, companies:general_information (post). The storefront script moves the placeholder in front of .ty-product-block__button when Position is “Before Add to cart”.

Caching

• Placeholder: product page data only; the products.view main block cache key gets kv_sep_state (license, placement) via schemas/block_manager/blocks.post.php.
• Rates: Registry::registerCache(['kv_sep', <key>], ['update_handlers' => [shipping, product, promotion, tax and our tables], 'ttl' => minutes * 60], 'time'). The key covers products, quantities, options, location, user groups, tax exemption, language, currency, storefront and the realtime/hint settings. Dates are computed after the cache, on every request.

Integrations

• Kavio Delivery Date & Time Slots (kv_delivery_date_time_slots, active and licensed): Eta::forGroup() for methods with their own transit there, else Eta::build() with its calendar engine and our transit days. Its .kv-ddts-eta--product element is hidden by our script after a successful estimate.
• Kavio Shipping Goal Progress Bar (kv_free_shipping_progress_bar, active and licensed): GoalCalculator on the calculated virtual cart.
• Every call to another add-on is guarded with class_exists and try/catch; a failure falls back to our own calendar or hint.

CSS classes

.kv-sep (box; --loading, --ready, --timeout), __head, __to, __place, __change, __best, __line, __price, __free, __via, __eta, __countdown, __hint, __more, __list, __row, __row-main, __row-eta, __meta, __note, __form, __field, __input, __apply. Colours use the custom properties --kv-sep-accent, --kv-sep-border, --kv-sep-muted, --kv-sep-bg on .kv-sep, so a theme can restyle the box without overriding rules.

JavaScript: Tygh.kvShippingEstimator.load(productId, {country, state, zipcode, city}) reloads an estimate.

Classes (Tygh\Addons\KvShippingEstimatorProduct)

Config (settings, license gate), Estimator (virtual cart, core calculation, cache), Dates (dates per method), Calendar (business-day engine), FreeHint, Repository (our tables, delivery time parsing), Storefront (view data), License\Client, Upgrade\Synchronizer.

File map

app/addons/kv_shipping_estimator_product/
  addon.xml  init.php  func.php
  controllers/frontend/kv_shipping_estimator_product.php   estimate, form, states
  controllers/frontend/products.post.php                   placeholder data of the product page
  controllers/backend/{shippings,products,companies}.post.php   admin field values
  controllers/backend/kv_shipping_estimator_product_license.php
  schemas/block_manager/blocks.post.php
  Tygh/Addons/KvShippingEstimatorProduct/*.php
design/backend/templates/addons/kv_shipping_estimator_product/{hooks,license}/
design/backend/css/addons/kv_shipping_estimator_product/license.less
var/themes_repository/responsive/templates/addons/kv_shipping_estimator_product/
  components/{placeholder,method_price,method_eta}.tpl  blocks/estimate.tpl
  views/kv_shipping_estimator_product/{estimate,form}.tpl
  hooks/products/product_detail_bottom.post.tpl  hooks/index/{styles,scripts}.post.tpl
var/themes_repository/responsive/css/addons/kv_shipping_estimator_product/styles.less
js/addons/kv_shipping_estimator_product/func.js
var/langs/en/addons/kv_shipping_estimator_product.po

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