Developer notes

Technical reference for developers who customize Smart Collections.

Add-on identity

Item	Value
Add-on id	kv_smart_collections
Function prefix	fn_kv_smart_collections_
Language variables	kv_smart_collections.*
CSS scope (admin)	.kv-sc, .kv-sc-cond
PHP namespace	Tygh\Addons\KvSmartCollections

Data model

Table	Content
?:kv_sc_collections	One row per collection: mode C (category) / V (blocks only), category_id, match_type, conditions (JSON), sort_by, limit_count, pins / excludes (product ids), schedule, sync state and counters.
?:kv_sc_products	The current product set of each collection with its position (parent products). Used by the block filling.
?:kv_sc_links	Every ?:products_categories row the add-on created (category, product, collection). Only these rows are ever changed or deleted, and only while their link_type is A.
?:kv_sc_queue	Products changed since the last incremental sync.

How a sync works

1. The rules compile into one SQL query on ?:products (each rule is an indexed EXISTS sub-query or a column condition), restricted to parent products and, in Ultimate, to the storefront’s own and shared products. Bestseller and rating rules use maps of units sold (settled order statuses) and ratings.
2. Pins come first, excludes are removed, the limit is applied.
3. ?:kv_sc_products is rewritten in that order.
4. In category mode the managed links are compared with the target (variation children follow their parent): new links are inserted as link_type = 'A' with position = rank, products already in the category are skipped, links no longer wanted are deleted, positions are updated. At most batch size changes per run; the rest follows on the next run. fn_update_product_count() updates the category counter.

PHP API

use Tygh\Addons\KvSmartCollections\Sync;
use Tygh\Addons\KvSmartCollections\Scheduler;

Sync::syncCollection($collection_id);   // full sync of one collection (license-gated callers only)
Sync::queue([$product_id]);             // queue products for the incremental sync
Scheduler::run('cron');                 // queue + due collections

Products of a collection in your own code (the block filling uses the same parameter):

list($products) = fn_get_products([
    'kv_sc_collection_id' => 12,
    'sort_by'             => 'kv_sc_position',
    'sort_order'          => 'asc',
    'limit'               => 8,
]);

Hooks used

Hook	Purpose
get_products	Block filling / kv_sc_collection_id parameter: joins the collection set, sorting kv_sc_position.
update_product_post, clone_product_post, tools_change_status	Queue the product for the incremental sync.
update_product_amount	Queue on stock changes when a collection uses a stock rule.
delete_product_post, delete_category_post	Clean up the add-on’s rows; disable collections of a deleted category.
import_post	Product imports mark every collection for the next sync.
dispatch_before_display	Admin fallback runner (no cron).

Block Manager: schemas/block_manager/blocks.post.php adds the filling kv_smart_collections to the core products block (cache update handlers kv_sc_products, kv_sc_collections, a license cache key); fillings.post.php adds its settings. Status changes of the add-on switch the placements of such blocks off and on (schemas/settings/actions.functions.post.php).

Console

php admin.php --dispatch=kv_smart_collections.cron            # sync run
php admin.php --dispatch=kv_smart_collections_license.check   # license check

File map

app/addons/kv_smart_collections/
  addon.xml  init.php  func.php
  controllers/backend/kv_smart_collections.php     list, editor, preview, sync, clear, CSV, console cron
  controllers/backend/block_manager.post.php       collections for the block filling selector
  controllers/frontend/kv_smart_collections.php    cron URL (key)
  schemas/block_manager/{blocks,fillings}.post.php
  schemas/menu/menu.post.php  schemas/permissions/admin.post.php
  schemas/settings/actions.functions.post.php
  Tygh/Addons/KvSmartCollections/
    Collections.php  Rules.php  Sync.php  Scheduler.php  Blocks.php  Editor.php  Csv.php  Config.php  StorageData.php
    License/  Upgrade/Synchronizer.php
design/backend/templates/addons/kv_smart_collections/
  views/kv_smart_collections/{manage,update,import}.tpl  components/{condition,preview}.tpl
  block_manager/collection_select.tpl  settings/cron_info.tpl  license/  hooks/
design/backend/css/addons/kv_smart_collections/  js/addons/kv_smart_collections/backend.js
var/langs/en/addons/kv_smart_collections.po

The add-on has no storefront templates: collection categories are core category pages and the block uses the core product list templates of your theme.

License

The license client (License\Client) gates every sync runner and the block filling. Cleanup actions (Clear links, delete, uninstall) and the admin pages are not gated. See License.