Developer notes

Architecture

• Add-on id kv_green_claims_checker, scheme 3.0, priority 2000 (after the SEO and Tags add-ons, so a product is checked after its SEO name and tags are saved). PHP 7.4 to 8.3, CS-Cart 4.17.2 to 4.21.x, all editions. No core files are changed.
• Classes in app/addons/kv_green_claims_checker/Tygh/Addons/KvGreenClaimsChecker/:
  • Matcher (pure PHP): normalises a field (HTML tags, scripts and styles removed, entities decoded, curly apostrophes, subscript digits), matches all terms of a language with one compiled regular expression per 200 terms (Unicode word boundaries, flexible separators, * wildcards), resolves overlaps (longest match wins), applies the allow-list, detects a quantified specification in the same sentence and builds the snippet.
  • Defaults: the default term list and allow-list.
  • Collector: reads the texts of a batch of products with a fixed number of queries (descriptions per active language, feature values with variant and feature names, tags, SEO names).
  • Scanner: checkProducts(), the batched full scan (start, step with a time budget and a row lock on the scan, cancel), the queue and the cron entry.
  • Store: terms, allow-list, findings (upsert by a hash of product, language, field, field reference and term, so review decisions survive re-checks), counters, summaries, queue and scans.
  • Moderation: the Multi-Vendor decision table (decide() is pure), holds, approve / reject.
  • Fixer: bulk replace in description columns: preview() (nothing saved), apply() (saves through fn_update_product() so core hooks, the vendor data premoderation and the add-on’s moderation run, and keeps a revision in kv_gcc_revisions), undo() (restores a batch; fields edited since are skipped). The occurrences come from Matcher::replaceTerm(), which uses the same matching, overlap and allow-list rules as scan() and maps the matches back to the stored HTML (entities and curly quotes kept).
  • Access: company scope (vendor / selected storefront) and the licence check; Config: settings; Csv: export, formula guard, term import.
• Tables: kv_gcc_terms, kv_gcc_allow, kv_gcc_findings, kv_gcc_products (counters and hold state), kv_gcc_scans, kv_gcc_queue, kv_gcc_revisions (previous texts of the last 30 replacements). All are dropped on uninstall (no legal records are kept: export first).

Hooks

Hook	Use
update_product_post	Vendor (MV): check now + moderation. Administrator: check up to five products per request inline, queue the rest; API and other areas queue.
tools_update_status_before_query	Vendor switching a product to Active / Hidden in a list: refused under Require review / Block while findings are at or above the hold severity.
tools_change_status	An administrator activating a held product lifts the hold.
delete_product_post, delete_company	Remove findings and counters.
init_templater_post	Upgrade synchronizer (only while an upgrade is pending).

Admin template hook products:tabs_content (post) and the controller products.post.php add the Green claims tab. Menu: schemas/menu/menu.post.php (Products), menu_vendor.post.php (vendor panel configurator).

Performance

• Nothing runs on storefront requests; the add-on ships no storefront templates, styles or scripts (full page cache: no effect on cached pages).
• A full scan reads the catalog in batches of 200 products (setting) by product id, with a time budget per step (8 s from the admin page, 50 s from the cron URL, 300 s from the console). Each batch needs about five queries plus the upserts of its findings.
• One product check (save hook) costs a few queries and a regex pass over its texts.
• Measured on the 4.17.2 Multi-Vendor demo store (251 products, 2 languages): full scan 2.1 s.

Permissions

• Administrators: view_catalog for viewing and the export, manage_catalog for every change and for the term lists, allow-list and submissions pages.
• Vendors (schemas/permissions/vendor_multivendor.post.php): dashboard, findings, export, scan of their own catalog (never the store-wide scan) and replace in their own texts (saved through the core product save) when “Vendors see their findings” is on; review, approve / reject, lists and cron are denied in the schema and in the controller. Every list and action is limited to the vendor’s company (Access::condition(), Access::ownProducts()).

Cron

php admin.php --dispatch=kv_green_claims_checker.cron --key=<key>
index.php?dispatch=kv_green_claims_checker.cron&key=<key>

The key is generated on install (setting cron_key, hidden). A wrong key answers 403.

Licence

License\Client (generated by kv license-client) verifies the licence for the store domain from the admin panel or cron. Without an active licence: scans, checks on save, replace and moderation are paused; findings, lists and the export stay available.

Extending

• Term and allow-list rows can be inserted directly into ?:kv_gcc_terms / ?:kv_gcc_allow (category one of generic, offsetting, label, whole, future, legal, custom; severity high, medium, low; allow kind context, label, reep).
• Queue products for a re-check: \Tygh\Addons\KvGreenClaimsChecker\Store::queue([$product_id, ...]).
• Check now: \Tygh\Addons\KvGreenClaimsChecker\Scanner::checkProducts([$product_id]) returns the counters per product.