give / vendor / vendor-prefixed / stellarwp / licensing-api-client / src / Tracing / TraceParent.php

TraceParent.php in GiveWP – Donation Plugin and Fundraising Platform 4.17.0, at vendor/vendor-prefixed/stellarwp/licensing-api-client/src/Tracing/TraceParent.php

129 lines 2.9 KB

Raw Download Zip

1	<?php declare(strict_types=1);
2
3	namespace Give\Vendors\LiquidWeb\LicensingApiClient\Tracing;
4
5	use InvalidArgumentException;
6
7	/**
8	* Immutable W3C traceparent value object.
9	*
10	* @see https://www.w3.org/TR/trace-context/#traceparent-header
11	*/
12	final class TraceParent
13	{
14	private string $version;
15
16	private string $traceId;
17
18	private string $parentSpanId;
19
20	private string $flags;
21
22	private function __construct(string $version, string $traceId, string $parentSpanId, string $flags) {
23	$this->version = $version;
24	$this->traceId = $traceId;
25	$this->parentSpanId = $parentSpanId;
26	$this->flags = $flags;
27	}
28
29	/**
30	* Parse and validate a W3C traceparent header value.
31	*
32	* @throws InvalidArgumentException
33	*/
34	public static function fromString(string $value): self {
35	$value = trim($value);
36
37	if ($value === '') {
38	throw new InvalidArgumentException('traceparent cannot be empty.');
39	}
40
41	$parts = explode('-', strtolower($value));
42
43	if (count($parts) !== 4) {
44	throw new InvalidArgumentException('traceparent must have 4 dash-delimited parts.');
45	}
46
47	$version = $parts[0];
48	$traceId = $parts[1];
49	$parentSpanId = $parts[2];
50	$flags = $parts[3];
51
52	if (!self::isHex($version, 2) \|\| $version === 'ff') {
53	throw new InvalidArgumentException('traceparent version must be 2 hex characters and not ff.');
54	}
55
56	if (!self::isIdentifier($traceId, 32)) {
57	throw new InvalidArgumentException('traceparent trace-id must be 32 non-zero hex characters.');
58	}
59
60	if (!self::isIdentifier($parentSpanId, 16)) {
61	throw new InvalidArgumentException('traceparent parent-id must be 16 non-zero hex characters.');
62	}
63
64	if (!self::isHex($flags, 2)) {
65	throw new InvalidArgumentException('traceparent flags must be 2 hex characters.');
66	}
67
68	return new self($version, $traceId, $parentSpanId, $flags);
69	}
70
71	/**
72	* Generate a new root traceparent value.
73	*/
74	public static function generate(bool $sampled = true): self {
75	return new self(
76	'00',
77	bin2hex(random_bytes(16)),
78	bin2hex(random_bytes(8)),
79	$sampled ? '01' : '00'
80	);
81	}
82
83	/**
84	* Return the normalized traceparent header string.
85	*/
86	public function header(): string {
87	return sprintf(
88	'%s-%s-%s-%s',
89	$this->version,
90	$this->traceId,
91	$this->parentSpanId,
92	$this->flags
93	);
94	}
95
96	/**
97	* Return the trace-id segment.
98	*/
99	public function traceId(): string {
100	return $this->traceId;
101	}
102
103	/**
104	* Return the parent span-id segment.
105	*/
106	public function parentSpanId(): string {
107	return $this->parentSpanId;
108	}
109
110	/**
111	* Return the trace-flags segment.
112	*/
113	public function flags(): string {
114	return $this->flags;
115	}
116
117	public function __toString(): string {
118	return $this->header();
119	}
120
121	private static function isHex(string $value, int $length): bool {
122	return strlen($value) === $length && ctype_xdigit($value);
123	}
124
125	private static function isIdentifier(string $value, int $length): bool {
126	return self::isHex($value, $length) && trim($value, '0') !== '';
127	}
128	}
129