Developer notes

Files

Path	Purpose
app/addons/kv_shipping_payment_restrictions/init.php, func.php	Hook registration and handlers (thin wrappers around the classes below).
Tygh/Addons/KvShippingPaymentRestrictions/Checkout.php	Applies the rules: shipping lists, product groups, payment lists, order placement check.
.../Evaluator.php	Rule order (“first matching rule decides”) and the condition checks.
.../Context.php, ProductData.php	What the conditions look at: package or cart products, totals, location, user groups, chosen shipping, time. Product categories (with parents), feature variants and tags are loaded in one batch per request.
.../Repository.php	Rules, messages and product tags; the active-rule cache.
.../Conditions.php, RuleForm.php, Options.php	Condition schema, input normalization and the editor option lists.
.../License/Client.php	License check client (generated from the shared Kavio Labs template).
controllers/backend/kv_shipping_payment_restrictions.php	Rule list and editor (admin and vendor panel).
controllers/backend/kv_shipping_payment_restrictions_license.php	“Check now” / cron license check.
design/backend/templates/addons/kv_shipping_payment_restrictions/license/info.tpl	License tab (points to the card).
design/backend/templates/addons/kv_shipping_payment_restrictions/license/card.tpl	License card (add-on page) / banner.
design/backend/templates/addons/kv_shipping_payment_restrictions/license/status_bar.tpl	Status chip/banner for own admin pages.
design/backend/templates/addons/kv_shipping_payment_restrictions/license/badge.tpl	Badge in Add-ons > Manage add-ons.
design/backend/templates/addons/kv_shipping_payment_restrictions/hooks/addons/	Tabs_content.pre.tpl (card), manage.post.tpl (badge).
design/backend/templates/addons/kv_shipping_payment_restrictions/hooks/index/styles.post.tpl	Loads license.less.
design/backend/css/addons/kv_shipping_payment_restrictions/license.less	Card, chip and badge styles (admin LESS variables).
design/backend/templates/addons/kv_shipping_payment_restrictions/	Admin templates; hooks/products/update_product_out_of_stock_actions.post.tpl adds the tag field.
var/themes_repository/responsive/templates/addons/kv_shipping_payment_restrictions/hooks/checkout/	Customer messages (checkout:shipping_methods_list and checkout:payments post hooks).

Database

Table	Content
?:kv_spr_rules	rule_id, company_id (0 = marketplace/all stores; vendor or storefront id), name, target (S/P), action (H hide / A always show), object_ids (comma list), match_type (A all / O any), scope (P package / C cart), conditions (JSON), priority, status, timestamps.
?:kv_spr_rule_descriptions	rule_id, lang_code, message.
?:kv_spr_product_tags	product_id, tag.

Condition JSON items: {"type":"subtotal","min":500,"max":null}, {"type":"products","op":"any","values":[12,15]}, {"type":"zipcodes","op":"in","values":["10*","30000-30999"]}, {"type":"time","from":1080,"to":360} (minutes), {"type":"dates","from":<ts>,"to":<ts>}. Unknown types never match.

Hooks used (identical in 4.17.2 and 4.21.2)

Hook	Why
calculate_cart_items	Remembers the cart being calculated (whole-cart context for package-level shipping filtering).
shippings_get_shippings_list_post	Removes hidden shipping methods before rates are requested (no carrier API calls for them); also hides them from the checkout’s “all shippings” list.
calculate_cart_content_after_shipping_calculation	Filters the calculated product groups (also when CS-Cart reuses cached rates) before core chooses the selected method, and attaches the customer messages to each group (kv_spr_messages).
prepare_checkout_payment_methods_before_get_payments / _after_get_payments	Evaluates payment rules; adds the hidden ids to the payment query parameters so the core static payment cache key differs per result, then removes the hidden payments. Covers the checkout list and the express-checkout buttons.
checkout_select_default_payment_method	Switches to the first available payment when the selected one became hidden.
get_payments_post	Admin order management (only with “Apply the rules when staff create or edit orders”).
allow_place_order_post	Server-side check of the chosen shipping methods and payment (parent order only).
before_dispatch (admin area and console only; static handler License\Client::onBeforeDispatch)	Runs the due license check and shows license notices (not on the add-on’s own pages, which show the status bar).
Admin template hooks addons:tabs_content (pre), addons:manage (post), index:styles (post)	License card at the top of the add-on page, license badge in Add-ons > Manage add-ons (moved into the add-on’s row), license.less.
update_product_post, delete_product_post, delete_shipping, delete_payment_post, delete_company	Tags and cleanup.

The rules apply in the storefront (area C, including the Storefront REST API for customers). In the admin area (A) they apply only with the “apply in admin” setting.

License check

Tygh\Addons\KvShippingPaymentRestrictions\License\Client verifies the license against the Kavio Labs license server.

• fn_kv_shipping_payment_restrictions_is_licensed() is the gate. When it returns false, the rule hook handlers return at once (calculate_cart_items, shippings_get_shippings_list_post, calculate_cart_content_after_shipping_calculation, prepare_checkout_payment_methods_before_get_payments / _after_get_payments, checkout_select_default_payment_method, get_payments_post, allow_place_order_post) and the checkout message modifiers (fn_kv_shipping_payment_restrictions_payment_messages, fn_kv_shipping_payment_restrictions_shipping_messages) return no messages. Every method is shown, no message is printed and no order is refused; the core checkout runs unchanged. The rule editor, product tags and cleanup hooks keep working.
• In the storefront the gate uses the current storefront’s host (Ultimate: only storefronts on a covered domain apply the rules); in the admin panel and console it means “licensed for at least one storefront”. It reads the stored state only (one storage read per request) and never contacts the server.
• No output of the add-on is inside a cached block (cart and checkout are not cached), so no block cache handler is needed.
• Request: POST https://cs-cart.kaviolabs.com/index.php?dispatch=kv_licenses.check with JSON {"v":1, "license", "addon", "version", "hosts":[…], "platform":{"version", "edition"}, "nonce"}, sent through Tygh\Http (3 s connect, 5 s total; kept out of the CS-Cart request log). The answer is accepted only when its Ed25519 signature matches a public key embedded in the client and it echoes the nonce.
• State: storage key kv_license_kv_shipping_payment_restrictions (?:storage_data), or var/kv_storage/kv_shipping_payment_restrictions/license.json while the full page cache is active, protected by an HMAC with the store’s crypt key.
• Cron: php admin.php --dispatch=kv_shipping_payment_restrictions_license.check.
• Admin UI: License\Client assigns the view data of the license card to $kv_lic_kv_shipping_payment_restrictions in its before_dispatch handler, only for administrators with the Manage settings privilege (update_settings); vendors never get it. The templates only read this variable, so they render nothing (and no error) while an older version of the PHP code is loaded, for example in the request that uploads a new zip over the installed add-on. PHP code can call fn_kv_shipping_payment_restrictions_license_ui($context). Every full page of the add-on’s own admin controllers (rule list, rule editor) includes license/status_bar.tpl as the first line of its mainbox: a green chip when licensed, the card as a compact banner otherwise. The add-on’s license notice is not shown on these pages (the bar shows the status); it appears on the next other admin page.
• The license check endpoint (kv_shipping_payment_restrictions_license.check) accepts only CSRF-protected POST requests of administrators, and console requests. Vendors cannot use it.
• Development stores only (http_host and https_host are development hosts): the constants KV_LICENSE_SERVER_URL, KV_LICENSE_TEST_HOST (act as if the development storefronts ran on that host) and KV_LICENSE_TEST_TIME_OFFSET (seconds). They are ignored on production hosts.

Caching and performance

Active rules are loaded once per request and language through Registry::registerCache() keyed on the rule tables, so saving a rule invalidates the cache. Condition results are memoized per rule and context hash; product attributes are loaded once per request in one query per attribute type. No queries run when there are no active rules for a target.

Full page cache (4.21)

Checkout and cart pages are never cached by the core full page cache, and the add-on prints nothing on cacheable pages. The rules never write ?:storage_data; the license state is written only by admin/console checks (to var/kv_storage/ while the full page cache is active).

Upgrades

The add-on ships Upgrade\Synchronizer: after files are replaced in place, the next admin request creates missing tables/columns, settings and language variables, and updates the add-on version.

Next steps

• FAQ
• Usage
• Overview

Third-party code

Tygh/Addons/KvShippingPaymentRestrictions/License/Ed25519.php (checks the signature of the license server’s answers on servers whose PHP has no sodium extension) is derived from paragonie/sodium_compat, ISC License, Copyright (c) 2016-2023 Paragon Initiative Enterprises and Copyright (c) 2013-2019 Frank Denis. The full license notice is in the file header.