McpObservabilityHelperTrait.php — WooCommerce 10.9.4

woocommerce / vendor / wordpress / mcp-adapter / includes / Infrastructure / Observability / McpObservabilityHelperTrait.php

woocommerce / vendor / wordpress / mcp-adapter / includes / Infrastructure / Observability Last commit date

Contracts 7 months ago ConsoleObservabilityHandler.php 7 months ago ErrorLogMcpObservabilityHandler.php 7 months ago McpObservabilityHelperTrait.php 7 months ago NullMcpObservabilityHandler.php 7 months ago

McpObservabilityHelperTrait.php

129 lines

1	<?php
2	/**
3	* Helper trait for MCP observability handlers providing shared utility methods.
4	*
5	* @package McpAdapter
6	*/
7
8	declare( strict_types=1 );
9
10	namespace WP\MCP\Infrastructure\Observability;
11
12	/**
13	* Trait McpObservabilityHelperTrait
14	*
15	* Provides shared utility methods for observability handlers including
16	* tag management, metric formatting, and sanitization functionality.
17	*/
18	trait McpObservabilityHelperTrait {
19	/**
20	* Error categories keyed by throwable class name.
21	*
22	* @used-by ::categorize_error() method.
23	*/
24	private static array $error_categories = array(
25	\ArgumentCountError::class => 'arguments',
26	\Error::class => 'system',
27	\InvalidArgumentException::class => 'validation',
28	\LogicException::class => 'logic',
29	\RuntimeException::class => 'execution',
30	\TypeError::class => 'type',
31	);
32
33	/**
34	* Get default tags that should be included with all metrics.
35	*
36	* @return array
37	*/
38	public static function get_default_tags(): array {
39	return array(
40	'site_id' => function_exists( 'get_current_blog_id' ) ? get_current_blog_id() : 0,
41	'user_id' => function_exists( 'get_current_user_id' ) ? get_current_user_id() : 0,
42	'timestamp' => time(),
43	);
44	}
45
46	/**
47	* Sanitize tags to ensure they are safe for logging and don't contain sensitive data.
48	*
49	* @param array $tags The tags to sanitize.
50	*
51	* @return array
52	*/
53	public static function sanitize_tags( array $tags ): array {
54	$sanitized = array();
55
56	foreach ( $tags as $key => $value ) {
57	// Convert to string and limit length to prevent log bloat.
58	$key = substr( (string) $key, 0, 64 );
59
60	// Convert value to string, handling null specially.
61	if ( null === $value ) {
62	$value = '';
63	} elseif ( is_scalar( $value ) ) {
64	$value = (string) $value;
65	} else {
66	$value = wp_json_encode( $value );
67	// wp_json_encode can return false on failure, ensure we have a string.
68	if ( false === $value ) {
69	$value = '';
70	}
71	}
72
73	// Remove potentially sensitive information patterns.
74	$value = preg_replace( '/\b(?:password\|token\|key\|secret\|auth)\b/i', '[REDACTED]', $value );
75
76	$sanitized[ $key ] = $value;
77	}
78
79	return $sanitized;
80	}
81
82	/**
83	* Format metric name to follow consistent naming conventions.
84	*
85	* @param string $metric The raw metric name.
86	*
87	* @return string
88	*/
89	public static function format_metric_name( string $metric ): string {
90	// Ensure metric starts with 'mcp.' prefix.
91	if ( ! str_starts_with( $metric, 'mcp.' ) ) {
92	$metric = 'mcp.' . $metric;
93	}
94
95	// Convert to lowercase and replace spaces/special chars with dots.
96	$metric = strtolower( $metric );
97	$metric = (string) preg_replace( '/[^a-z0-9_\.]/', '.', $metric );
98	$metric = (string) preg_replace( '/\.+/', '.', $metric ); // Remove duplicate dots.
99	// Remove leading/trailing dots.
100
101	return trim( $metric, '.' );
102	}
103
104	/**
105	* Merge default tags with provided tags.
106	*
107	* @param array $tags The user-provided tags.
108	*
109	* @return array
110	*/
111	public static function merge_tags( array $tags ): array {
112	$default_tags = self::get_default_tags();
113	$merged_tags = array_merge( $default_tags, $tags );
114
115	return self::sanitize_tags( $merged_tags );
116	}
117
118	/**
119	* Categorize an exception into a general error category.
120	*
121	* @param \Throwable $exception The exception to categorize.
122	*
123	* @return string
124	*/
125	public static function categorize_error( \Throwable $exception ): string {
126	return self::$error_categories[ get_class( $exception ) ] ?? 'unknown';
127	}
128	}
129