Developer notes

Overview · Installation · Configuration · Usage · FAQ

How it plugs into checkout

• Install registers a realtime shipping service (?:shipping_services, module kv_vendor_table_rates, code table). Its class is Tygh\Shippings\Services\KvVendorTableRates (in the add-on’s Tygh/ directory). It calculates locally and never sends a request.
• Every table-rate method is a core shipping method (?:shippings) owned by the vendor (company_id), with rate_calculation = R, the service id and service_params = {kv_vstr: Y}. Name, status and delivery time live in the core tables.
• Checkout uses the core flow: fn_calculate_cart_content() → Shippings::groupProductsList() (one group per vendor) → Shippings::getShippingsList() → Shippings::calculateRates() → RealtimeServices. The service returns the price, or false (method not offered) when no row matches.
• Core keeps a rate only when the method has rate_info (a core rate for the customer’s rate area). The shippings_get_shippings_list_post hook adds a neutral rate_info to table-rate methods without one and passes the package’s product lines (product and category ids) for surcharges. A real core rate for the area is added on top, as core does for every realtime service.
• Core then applies product shipping freight, free-shipping promotions, the “Free shipping” product flag (via the method’s free_shipping option) and the method’s taxes.

Price

Calculator::quote($table, $rates, $surcharges, $package) (pure, no database): basis value (weight W, subtotal C, items I; core’s 0.001 weight counts as 0) → best row (matchRow: destination specificity postcode 4 + state 2 + country 1, then row order; range from <= value <= to, to 0 = open) → rate + unit (× value, or % of subtotal) + surcharges + handling → min/max → free over → rounded to cents.

Hooks

Hook	Use	Core reference
shippings_get_shippings_list_post	product lines, neutral rate_info, hide methods of vendors without access	Shippings.php 4.17.2:513, 4.21.2:517
shippings_get_shipping_for_test_post	core “Test rate calculation” tab	4.17.2:584, 4.21.2:588
calculate_cart_content_before_shipping_calculation	adds the add-on’s tables to the shipping-rate cache tables	fn.cart.php
update_shipping_post	a method switched to the Table rates service in the core page gets a table	fn.cart.php
delete_shipping, delete_company, delete_product_post	cleanup

The arguments are identical in 4.17.2 and 4.21.2. Every handler checks fn_allowed_for('MULTIVENDOR').

Data model

Table	Contents
?:kv_vstr_tables	type M (method, shipping_id) or T (template, name, note, template_delivery_time), company_id, basis, free_over, handling_fixed, handling_percent, min_rate, max_rate, locked, template_id, status (templates)
?:kv_vstr_rates	table_id, position, country, state, postcodes, cond_from, cond_to, rate, unit_rate, delivery_time
?:kv_vstr_surcharges	table_id, object_type P/C, object_id, amount, per_item

Permissions and scoping

Admin pages use the core privileges view_shipping (GET) and manage_shipping (POST). In the vendor panel the controller limits every table to the vendor’s company, never shows templates for editing, refuses locks and other vendors’ ids. The editor posts the grid as JSON (rates_json, surcharges_json) so large tables stay under max_input_vars; plain rates[]/surcharges[] arrays are accepted too.

Full page cache

No storefront templates or output. The service and hooks write nothing to the session or storage_data.

License check

See License. The gate fn_kv_vendor_shipping_table_rates_is_licensed() covers every change in the editor (save, import, apply template, create, delete, status, lock) and the cart tester. Checkout never depends on it.

File map

Path	Purpose
app/addons/kv_vendor_shipping_table_rates/addon.xml, init.php, func.php	Scheme, settings, tables, install/uninstall, hooks
controllers/backend/kv_vendor_shipping_table_rates.php	Methods, new method, templates, editor, save, import/export, apply template, tester (AJAX), bulk actions
Tygh/Shippings/Services/KvVendorTableRates.php	Shipping service
Tygh/Addons/KvVendorShippingTableRates/Calculator.php	Price engine
.../Checkout.php	Hook glue and the cart tester
.../Repository.php	Tables, rows, surcharges, templates, core method sync
.../Input.php, Csv.php	Validation, CSV
.../Installer.php, Report.php, Config.php	Service registration, 30-day report, settings and access
.../License/*, controllers/backend/kv_vendor_shipping_table_rates_license.php	License client and “Check now”
.../Upgrade/Synchronizer.php	Self-healing upgrades
schemas/permissions/*, schemas/menu/*	Privileges, vendor access, menu
design/backend/templates/addons/kv_vendor_shipping_table_rates/	Pages, grid rows, tester result, core service tab, license UI
js/addons/kv_vendor_shipping_table_rates/backend.js, design/backend/css/addons/kv_vendor_shipping_table_rates/	Editor script and styles
var/langs/en/addons/kv_vendor_shipping_table_rates.po	Language variables