Developer notes

Overview · Installation · Configuration · Usage · FAQ

How a request is checked

1. get_route hook (priority 4000, after SEO routing), storefront index.php only. Never runs for admin.php, vendor.php, api.php or the console.
2. Off switches: the Enable setting, var/kv_bot_country_blocker.off, the constant KV_BCB_DISABLED.
3. Exempt: payment_notification.*, /robots.txt, the add-on’s own dispatch and the merchant’s exempt list.
4. The compiled ruleset of the storefront company, var/kv_bot_country_blocker/ruleset_<company_id>.php (var_export, served from OPcache, rebuilt after any change). A visitor that matches nothing costs no SQL query; the licence state is read only when a decision would be enforced.
5. Administrator IPs, active bans, verified search engines, then the rules in order.
6. Decision: log entry (+ daily counters) and, when enforced, the response: 403 page, challenge page, redirect, or the checkout restriction in before_dispatch.

Responses send Cache-Control: no-store, private and X-Robots-Tag: noindex; AJAX requests get a JSON 403.

Full page cache (CS-Cart 4.21, Varnish)

Pages that Varnish serves never reach PHP, so the blocker sees cache misses, POST requests, AJAX, cart, checkout, account and search pages. The add-on adds no storefront markup, sets no cookie on normal pages and writes no storage_data, so cached pages stay shared. For full coverage at the edge use the Cloudflare expressions (Tools tab) or equivalent Varnish/WAF rules.

The full page cache turns every write to a database table into a cache purge (BAN) for that table’s cache tag. Since 1.0.1 all add-on tables (kv_bcb_rules, kv_bcb_bans, kv_bcb_admin_ips, kv_bcb_dns, kv_bcb_rate, kv_bcb_log, kv_bcb_stats) are added to ignore_cache_tags (schemas/full_page_cache/varnish.post.php): rate limit buckets, log rows, statistics, bans and rule hit counters written during a visit never purge cached pages. None of these tables changes what a storefront page shows. On CS-Cart 4.17 / 4.18 (no full page cache) the file is not used.

Data

Table	Content
?:kv_bcb_rules	rules (company, position, type, values, list URL + downloaded ranges, action, params JSON, hits)
?:kv_bcb_bans	temporary bans (IP, company, rule, expiry)
?:kv_bcb_admin_ips	IP addresses seen in the admin panel
?:kv_bcb_dns	reverse DNS results of search engine crawlers (7 days)
?:kv_bcb_rate	token buckets when APCu is not available
?:kv_bcb_log	decisions
?:kv_bcb_stats	daily counters (action, country, bot, rule)

Files: var/kv_bot_country_blocker/ruleset_*.php, var/kv_bot_country_blocker/geo/{country,asn}.mmdb.

Hooks used

• PHP: get_route, before_dispatch (identical arguments in 4.17.2 and 4.21.2), init_templater_post (upgrade synchronizer).
• Controllers: robots.pre.php (robots.txt served by CS-Cart), own backend controller kv_bot_country_blocker.
• Settings actions: robots_ai, add-on status.

Console

php admin.php --dispatch=kv_bot_country_blocker.cron

Runs log retention, removes expired bans and idle buckets, refreshes list URLs and, when enabled, the monthly GeoIP update.

Development constants (local_conf.php, tests only)

KV_BCB_DISABLED (switch off), KV_BCB_TEST_DNS (ip=host pairs instead of DNS), KV_BCB_TEST_SOURCE_DIR (local list files), KV_BCB_TEST_NO_APCU, KV_BCB_TEST_NO_EXIT.

File map

app/addons/kv_bot_country_blocker/
  addon.xml, init.php, func.php
  controllers/backend/kv_bot_country_blocker.php, kv_bot_country_blocker_license.php
  controllers/frontend/kv_bot_country_blocker.php, robots.pre.php
  schemas/menu/{menu,actions}.post.php, schemas/permissions/admin.post.php, schemas/settings/actions.functions.post.php
  Tygh/Addons/KvBotCountryBlocker/
    Engine.php (request check)  Rules.php (rules + compiled ruleset)  Ip.php  Geo.php  Bots.php  Presets.php
    Challenge.php  Response.php (pages)  RateLimiter.php  Bans.php  Log.php  Export.php  RobotsTxt.php
    Sources.php  Cron.php  Installer.php  StorageData.php  License/  Upgrade/Synchronizer.php
design/backend/templates/addons/kv_bot_country_blocker/ (views, components, settings, license, hooks)
design/backend/css/addons/kv_bot_country_blocker/ (styles.less, license.less)
js/addons/kv_bot_country_blocker/func.js
var/langs/en/addons/kv_bot_country_blocker.po

License check

Tygh\Addons\KvBotCountryBlocker\License\Client verifies the license for the store’s domain with cs-cart.kaviolabs.com once a day from the admin panel (signed answers, Ed25519). The storefront only reads the stored result.