Weave Code
Laravel Spectra Laravel Package
spectra-php/laravel-spectra
Laravel Spectra is the Laravel integration for the Spectra PHP package. It provides config publishing, service-provider registration, and framework-friendly helpers so you can add Spectra to Laravel apps with minimal setup and familiar conventions.
Laravel Spectra integrates the Spectra PHP library with Laravel, making it simple to generate and maintain OpenAPI documentation for your application. It follows Laravel conventions so your API spec can stay close to the routes, controllers, and requests you already write.
- First-class Laravel integration via a service provider
- Publishable configuration for project-specific setup
- Generates OpenAPI specs from your application
- Customizable output for different APIs and environments
- Easy Composer installation and lightweight footprint
Frequently asked questions about Laravel Spectra
- What does the laravel-spectra package do?
- Spectra is an observability layer for AI and LLM calls in Laravel applications. It instruments Laravel's HTTP client and the major AI SDKs, records a row for every AI call, calculates token and media costs, and exposes daily aggregates, budgets, alerts, a real-time dashboard and OpenTelemetry export. Think of it as the system of record for what AI costs you per user, tenant, feature and request.
- Which AI providers and SDKs does Spectra support?
- It automatically tracks requests to OpenAI, Anthropic, Gemini, Mistral and nine other providers, thirteen in total. On the SDK side it instruments Prism, the Laravel AI SDK, openai-php and Guzzle, so most AI traffic in a Laravel app is captured without code changes. Calls made outside Laravel, such as from Python services or edge workers, are not tracked.
- How do I install laravel-spectra in a Laravel app?
- Install it with Composer using spectra-php/laravel-spectra, then publish the config and migrations and run your migrations. Optionally schedule the spectra:prune command to control data retention. For budget alerts to work correctly you also need a shared, persistent cache store such as Redis or the database driver.
- Which Laravel versions does laravel-spectra support?
- Version 2 drops Laravel 11, so you need a newer Laravel release before upgrading. Check the composer.json constraints in the repository for the exact framework and PHP floor. If you are still on Laravel 11, plan the framework upgrade first because it has its own blast radius.
- How does Spectra calculate token and media costs?
- Spectra prices each recorded call against its model catalog, covering text tokens and media such as images and audio, and stores the computed cost alongside the request. Provider-reported cost tiers now override request tiers, which makes reported spend more accurate than in 1.x. Currency conversion is configurable through spectra.costs.exchange_rates in the config file.
- How do per-user budgets and budget alerts work?
- You define budgets per user or tenant, and Spectra evaluates spend against them as calls are recorded. In v2 alerts fire once per budget period and use the cache to deduplicate, which fixes both duplicate alerts on PHP-FPM and missing alerts in long-running workers. This only works with a shared persistent cache store, so avoid the array or per-node file cache in production, and make sure something downstream consumes the alert.
- How does OpenTelemetry export and trace propagation work in Spectra?
- Spectra creates one trace per HTTP request, queued job or console command and propagates it into dispatched jobs. It can adopt an inbound W3C traceparent as the parent span, so it slots into an existing OpenTelemetry setup. The behavior is controlled by the tracking.trace_per_request and tracking.use_traceparent config keys.
- Is it safe to upgrade laravel-spectra from 1.x to 2.x?
- The install mechanics are simple, but reported costs will step up at the upgrade boundary. Several 1.x underbilling bugs are fixed, including Anthropic cache reads and writes, Gemini thinking and tool-use tokens, xAI reasoning tokens, and provider-reported tiers now taking precedence. Historical rows are not automatically made comparable, so confirm with the maintainers whether a reprice or backfill is supported and annotate the discontinuity before comparing trends or budget baselines.
- What production concerns should I watch for with Spectra?
- Save failures now report instead of throwing into your application, which protects availability but means tracking data can be silently dropped, so wire that reporting channel into your alerting. The package is a scoped service, which fixes state leaking across requests in Octane and queued jobs but may change behavior in in-house code that held Spectra state between requests. Also review the migration size and locking profile on the tracked-request table at your current row counts and growth rate.
- Does Spectra track AI calls made outside Laravel?
- No. Spectra instruments Laravel's HTTP client and the AI SDKs running inside your Laravel application. AI calls from Python services, edge workers or other runtimes are invisible to it, so your cost picture will silently under-report unless those services are tracked separately.
Weaver
How can I help you explore Laravel packages today?