surecookie / inc / modules / automatic-scanning / classifier.php

classifier.php in SureCookie – GDPR Cookie Consent Banner, Cookie Scanner & Script Blocking trunk, at inc/modules/automatic-scanning/classifier.php

127 lines 3.8 KB

Raw Download Zip

1	<?php
2	/**
3	* Automatic Scanning classifier.
4	*
5	* Rule-based suggestion of a category (Necessary / Analytics / Marketing /
6	* Preferences) for newly-detected cookies, with a confidence score. Pure
7	* functions - they only suggest; applying the category (auto-apply) is a Pro
8	* feature. The `surecookie_auto_scan_classify` filter is the AI extension hook.
9	*
10	* @package SureCookie\Inc\Modules\AutomaticScanning
11	* @since 1.2.0
12	*/
13
14	namespace SureCookie\Inc\Modules\AutomaticScanning;
15
16	if ( ! defined( 'ABSPATH' ) ) {
17	exit; // Exit if accessed directly.
18	}
19
20	/**
21	* Classifier
22	*
23	* @since 1.2.0
24	*/
25	class Classifier {
26	/**
27	* Cached rules so the array is built only once per request.
28	*
29	* @var array<int, array{name_regex:string, category:string, confidence:int}>\|null
30	* @since 1.2.0
31	*/
32	private static $rules_cache = null;
33
34	/**
35	* Built-in classification rules, evaluated in order (first match wins).
36	*
37	* Each rule: name_regex (matched against the cookie name), the plugin
38	* category key it maps to, and a confidence score (0-100).
39	*
40	* @since 1.2.0
41	* @return array<int, array{name_regex:string, category:string, confidence:int}>
42	*/
43	public static function default_rules(): array {
44	if ( self::$rules_cache !== null ) {
45	return self::$rules_cache;
46	}
47
48	self::$rules_cache = [
49	// Strictly necessary (session, auth, security, commerce sessions).
50	[
51	'name_regex' => '/^(PHPSESSID\|XSRF-TOKEN\|csrftoken\|__cf_bm\|cf_clearance\|wordpress_(logged_in_\|sec_)?\|wp-settings\|woocommerce_\|wp_woocommerce_session_\|edd_)/i',
52	'category' => 'essential',
53	'confidence' => 95,
54	],
55	// Analytics (GA, Hotjar, Clarity, Segment).
56	[
57	'name_regex' => '/^(_ga(_.+)?\|_gid\|_gat.\|__utm.\|_hj.*\|_clck\|_clsk\|ajs_)/i',
58	'category' => 'analytics',
59	'confidence' => 90,
60	],
61	// Marketing / advertising (Meta, Google Ads, DoubleClick, TikTok, LinkedIn, Bing).
62	[
63	'name_regex' => '/^(_fbp\|fr\|_gcl_.+\|IDE\|test_cookie\|_ttp\|personalization_id\|li_sugr\|bcookie\|bscookie\|MUID\|_uetsid\|_uetvid)/i',
64	'category' => 'marketing',
65	'confidence' => 90,
66	],
67	// Preferences (language / localization).
68	[
69	'name_regex' => '/^(pll_language\|wp-wpml_current_language\|_icl_.+\|googtrans\|wp_lang)/i',
70	'category' => 'functional',
71	'confidence' => 85,
72	],
73	];
74
75	return self::$rules_cache;
76	}
77
78	/**
79	* Classify a cookie into a suggested category with a confidence score.
80	*
81	* Falls back to the cookie's existing (SaaS-assigned) category with zero
82	* confidence when no rule matches.
83	*
84	* @param array<string, mixed> $cookie Cookie data (expects at least 'name').
85	* @since 1.2.0
86	* @return array{category:string, confidence:int, matched_rule:string}
87	*/
88	public static function classify( array $cookie ): array {
89	$name = (string) ( $cookie['name'] ?? '' );
90
91	$result = [
92	'category' => (string) ( $cookie['category'] ?? 'uncategorized' ),
93	'confidence' => 0,
94	'matched_rule' => '',
95	];
96
97	if ( $name !== '' ) {
98	foreach ( self::default_rules() as $rule ) {
99	$pattern = $rule['name_regex'] ?? '';
100
101	if ( $pattern !== '' && preg_match( $pattern, $name ) ) {
102	$result = [
103	'category' => (string) $rule['category'],
104	'confidence' => (int) $rule['confidence'],
105	'matched_rule' => (string) $pattern,
106	];
107	break;
108	}
109	}
110	}
111
112	/**
113	* Filters the classification result for a cookie.
114	*
115	* The future AI classification module (or the MCP classify ability) can
116	* hook this to resolve low-confidence / unmatched cookies.
117	*
118	* @since 1.2.0
119	*
120	* @param array{category:string, confidence:int, matched_rule:string} $result Rule-based result.
121	* @param array<string, mixed> $cookie The cookie being classified.
122	*/
123	$filtered = apply_filters( 'surecookie_auto_scan_classify', $result, $cookie );
124	return is_array( $filtered ) ? $filtered : $result;
125	}
126	}
127