Utilities and Helpers

This document provides an overview of the foundational utility classes and traits that support the core Sentry integration. These components provide reusable functionality for span lifecycle management, event origin resolution, and SDK identification, enabling features and integrations throughout the package to interact with Sentry consistently.

The utilities covered in this section include:

• Span Management Traits (Section 6.1) - Provides methods for working with Sentry spans and checking sampling status
• Event Origin Resolution (Section 6.2) - Analyzes debug backtraces to identify source code locations where events originate
• Version and SDK Identification (Section 6.3) - Provides SDK identification and versioning information for Sentry telemetry

For information about how these utilities are used in monitoring features, see Monitoring Features.

Overview of Utility Components

Span Management

The WorksWithSpans trait provides methods for safely working with Sentry spans, ensuring operations only proceed when spans are actively being sampled. This prevents unnecessary overhead when Sentry is not collecting trace data.

Span Management Trait Flow

The trait provides two key methods:

• getParentSpanIfSampled() - Returns the current span only if it exists and is being sampled
• withParentSpanIfSampled(callable $callback) - Executes a callback with the parent span if available

For detailed documentation, see Section 6.1.

Sources: src/Traits/WorksWithSpans.php1-36

Event Origin Resolution

The ResolvesEventOrigin trait identifies the source code location where Sentry events originate by analyzing debug backtraces. This enables features to attach precise file paths and line numbers to breadcrumbs and spans.

Origin Resolution Flow

The trait provides two resolution methods:

• resolveEventOrigin() - Returns array with code.filepath, code.function, and code.lineno
• resolveEventOriginAsString() - Returns simple string format filepath:lineno

The backtrace is limited to 20 frames for performance, and the BacktraceHelper service filters out vendor/framework code to find the first application frame.

For detailed documentation, see Section 6.2.

Sources: src/Traits/ResolvesEventOrigin.php1-51

SDK Identification

The Version class provides SDK identification and versioning information that is sent with all Sentry events. This allows Sentry to identify which SDK and version generated the telemetry data.

Version Class Constants

Constant	Value	Purpose
SDK_IDENTIFIER	"sentry.php.hypervel"	Identifies this package as the Hypervel Sentry SDK
SDK_VERSION	"3.1.0"	Default version if not detected from Composer

The class provides two static methods:

• getSdkIdentifier() - Returns the SDK identifier string
• getSdkVersion() - Returns version from Composer metadata or falls back to SDK_VERSION

The version information is set on the Sentry client during initialization by the ClientBuilderFactory.

For detailed documentation, see Section 6.3.

Sources: src/Version.php1-25

Trait Usage Across Features

The utility traits are used throughout the codebase to provide consistent Sentry integration patterns:

Sources: src/Traits/WorksWithSpans.php1-36 src/Traits/TracksPushedScopesAndSpans.php1-94 src/Traits/ResolvesEventOrigin.php1-51