Installation

Requirements

• PHP 8.4 or higher
• Laravel 12.x

Install the Package

You may install Spectra into your project using the Composer package manager:

composer require spectra-php/laravel-spectra

After installing Spectra, publish its assets and run the database migrations using the spectra:install Artisan command:

php artisan spectra:install

The installer will guide you through four steps: publishing the configuration file to config/spectra.php, publishing the database migrations, running the migrations to create the seven Spectra tables, and optionally importing the default pricing catalog. Each step prompts for confirmation so you can control exactly what happens.

TIP

You can always import or update pricing data later with php artisan spectra:pricing --force. The pricing catalog is database-driven and can also be managed through the dashboard UI.

If you prefer to run each step manually instead of using the interactive installer:

php artisan vendor:publish --tag=spectra-config
php artisan vendor:publish --tag=spectra-migrations
php artisan migrate
php artisan spectra:pricing --force

Configuration

After publishing Spectra's assets, its primary configuration file will be located at config/spectra.php. This configuration file allows you to control every aspect of Spectra's behavior — storage settings, persistence mode, dashboard options, cost calculation, budget enforcement, and integration settings. Each option includes a description of its purpose, so be sure to explore the file thoroughly. For a complete reference, see Configuration.

The most important setting to be aware of is the master switch:

'enabled' => env('SPECTRA_ENABLED', true),

When set to false, Spectra does nothing — no interception, no tracking, no database writes. This allows you to disable observability entirely in specific environments without removing the package.

Dashboard Authorization

The Spectra dashboard may be accessed via the /spectra route. By default, you will only be able to access this dashboard in the local environment. The dashboard is protected by a Laravel gate called viewSpectra, which controls access in non-local environments. You are free to modify this gate as needed to restrict access to your Spectra installation:

use Illuminate\Support\Facades\Gate;

// In your AuthServiceProvider or AppServiceProvider:
Gate::define('viewSpectra', function ($user) {
    return in_array($user->email, [
        '[email protected]',
    ]);
});

You may also add middleware to the dashboard routes via the configuration file. This is useful for enforcing authentication or other access controls at the route level:

'dashboard' => [
    'middleware' => ['web', 'auth'],
],

The dashboard path is configurable via the SPECTRA_PATH environment variable or the dashboard.path configuration option:

'dashboard' => [
    'path' => env('SPECTRA_PATH', 'spectra'),
],

Separate Database

For high-volume applications, you may want Spectra to use its own database connection. This isolates observability writes from your application database and prevents Spectra from competing with your application queries for connection pool resources. To configure a separate connection, set the storage.connection option:

// config/spectra.php
'storage' => [
    'connection' => env('SPECTRA_DB_CONNECTION', 'spectra'),
],

Then define the corresponding connection in config/database.php:

'connections' => [
    'spectra' => [
        'driver' => 'mysql',
        'host' => env('SPECTRA_DB_HOST', '127.0.0.1'),
        'database' => env('SPECTRA_DB_DATABASE', 'spectra'),
        'username' => env('SPECTRA_DB_USERNAME', 'root'),
        'password' => env('SPECTRA_DB_PASSWORD', ''),
        // ...
    ],
],

Run migrations on the separate connection with:

php artisan migrate --database=spectra