Installation and Setup

This page guides you through installing the Hypervel Sentry integration package and performing initial setup. It covers package installation via Composer, service provider registration, configuration file publishing, and basic DSN configuration required to connect to Sentry.

For detailed configuration options including sampling rates, feature toggles, and integration settings, see Configuration. For understanding how the service provider bootstraps the system, see Service Provider.

---

Requirements

The Hypervel Sentry integration has the following system requirements:

Requirement	Version	Purpose
PHP	^8.2	Minimum PHP version
hypervel/cache	^0.3	Cache monitoring integration
hypervel/console	^0.3	Console command support
hypervel/core	^0.3	Core framework functionality
hypervel/object-pool	^0.3	Connection pooling for HTTP transport
hypervel/support	^0.3	Helper functions and utilities
sentry/sentry	^4.15.0	Official Sentry PHP SDK

Sources: composer.json27-34

---

Installation via Composer

Install the package using Composer:

This command adds the hypervel/sentry package to your project and installs all required dependencies.

Installation Flow Diagram

Sources: composer.json1-49

---

Service Provider Auto-Registration

The SentryServiceProvider is automatically registered by the Hypervel framework through the package discovery mechanism. The provider class is declared in the composer.json file's extra.hypervel.providers array.

Auto-Discovery Configuration

The service provider is defined at composer.json43-47:

No manual registration is required. The provider automatically bootstraps when the application starts.

Sources: composer.json39-47

---

Configuration Publishing

After installation, publish the configuration file to customize Sentry integration settings:

This command copies the default configuration file to your application's config directory, creating:

config/sentry.php

The published configuration file contains all available options with sensible defaults. The file structure includes:

Section	Purpose
dsn	Sentry Data Source Name for connecting to your project
environment	Application environment (production, staging, etc.)
sample_rate	Error event sampling rate (0.0 to 1.0)
traces_sample_rate	Performance trace sampling rate
enable_tracing	Enable/disable distributed tracing
breadcrumbs	Configure breadcrumb capture for various subsystems
integrations	List of Sentry integration classes to enable
features	List of monitoring feature classes to enable
tracing	Performance monitoring feature flags

Configuration File Structure

Sources: config/sentry.php1-136

---

Basic Configuration

Setting the DSN

The DSN (Data Source Name) is the only required configuration parameter. It connects your application to your Sentry project.

Step 1: Create a Sentry project at https://sentry.io

Step 2: Copy the DSN from your Sentry project settings

Step 3: Add the DSN to your .env file:

The configuration file reads this value at config/sentry.php20:

Environment Configuration

Configure the application environment to help organize errors in Sentry:

This value is automatically used by Sentry, as shown at config/sentry.php30:

Optional: Configure Sampling Rates

For high-traffic applications, adjust sampling rates to control data volume:

Minimum Configuration Checklist

Sources: config/sentry.php20 config/sentry.php30 config/sentry.php33 config/sentry.php39

---

Verifying Installation

After configuration, verify the Sentry integration is working correctly using the built-in test command:

This command sends a test exception to Sentry. If successful, you should see the event appear in your Sentry project dashboard within a few seconds.

Verification Flow

Troubleshooting

If the test command fails:

1. Verify DSN format: Ensure SENTRY_DSN is correctly formatted
2. Check network connectivity: Ensure your server can reach sentry.io
3. Review error logs: Check Hypervel logs for specific error messages
4. Verify PHP version: Ensure PHP 8.2 or higher is installed
5. Clear config cache: Run php bin/hyperf.php config:clear

Sources: composer.json27

---

Component Initialization

When the Hypervel application boots, the following initialization sequence occurs:

Initialization Sequence Diagram

Key components initialized:

Component	Class	Purpose
Service Provider	Hypervel\Sentry\SentryServiceProvider	Orchestrates initialization
Client Builder	Hypervel\Sentry\ClientBuilderFactory	Configures Sentry SDK client
Hub	Sentry\State\Hub	Central API for Sentry operations
Features	Various Feature classes	Enable monitoring subsystems

Sources: composer.json44-46 config/sentry.php85-92

---

Next Steps

After successful installation and verification:

1. Configure features: Review and enable/disable monitoring features in Configuration
2. Customize integrations: Learn about available integrations at Integrations and Aspects
3. Set up logging: Configure Sentry log channels at Logging Integration
4. Tune performance monitoring: Adjust sampling and tracing settings in Configuration
5. Review feature documentation: Explore individual feature capabilities starting at Monitoring Features

Feature Enablement Overview

All features are enabled by default and can be toggled individually through configuration.

Sources: config/sentry.php85-92 config/sentry.php61-76 config/sentry.php111-124