Weave Code
Context Laravel Package
open-telemetry/context
Immutable, execution-scoped context propagation for PHP based on the OpenTelemetry specification. Activate contexts with scopes and detach them safely, with optional fiber support and guidance for event loops.
Context implementation for OpenTelemetry PHP.
Frequently asked questions about Context
- What is open-telemetry/context used for in a PHP application?
- It provides the immutable, execution-scoped context propagation primitive defined by the OpenTelemetry specification. It stores the ambient current context, lets you activate a modified context through a scope, and requires you to detach that scope when the work finishes. It is not an observability product itself; it is the substrate that carries trace, span, and baggage state across execution boundaries underneath the OpenTelemetry PHP API and SDK.
- How do I install open-telemetry/context in a Laravel project?
- Run composer require open-telemetry/context, but in practice most teams get it pulled in transitively by the OpenTelemetry PHP SDK rather than requiring it explicitly. It is framework-agnostic and PSR-friendly, so it slots underneath Laravel without touching the container, middleware, or logging stack. Installation is trivial; the real work is the discipline of pairing every activate() call with detach().
- Why must activate() be paired with detach() in a finally block?
- Every activate() call returns a scope that must be detached, otherwise the modified context stays active and leaks into subsequent code. The documented pattern is to assign the scope, run your work inside a try block, and call $scope->detach() in the finally block so cleanup happens even when an exception is thrown. Skipping detach() causes wrong parent spans and context bleed between requests or jobs.
- What are debug scopes and should I disable them?
- By default, scopes created by activate() warn on invalid and missing detach() calls in non-production environments, which turns an otherwise invisible class of bug into a visible warning during development. Keep them enabled in development and staging as your primary safety net during rollout. Setting OTEL_PHP_DEBUG_SCOPES_DISABLED to a truthy value disables the warnings and is only recommended for applications that use exit or die, where the notices are unavoidable.
- Does open-telemetry/context create spans or export traces?
- No. It moves context across execution boundaries but does not create spans, sample them, export them, or instrument Laravel. Value only materializes when it is paired with the OpenTelemetry PHP API and SDK, exporters such as OTLP or Zipkin, and Laravel-specific instrumentation. Treat it as necessary but not sufficient, and plan it as one line item inside an observability program of work rather than a deliverable on its own.
- Does open-telemetry/context work with Laravel Octane, Swoole, or RoadRunner?
- The package is framework-agnostic and safe to run under long-lived workers, but async coverage depends on your runtime. Fiber-based automatic propagation has hard constraints, and fiber observers are explicitly unsafe on ZTS builds, so validate the runtime before committing. If fiber support is not viable, fall back to manual event-loop binding with the documented bindContext pattern.
- What is required to enable fiber support in open-telemetry/context?
- Fiber support requires an NTS build, ext-ffi, and OTEL_PHP_FIBERS_ENABLED set to a truthy value. For non-CLI SAPIs you also need vendor/autoload.php preloaded when ffi.enable is set to preload. Confirm these conditions in your deployment environment before planning async coverage, since they are runtime constraints rather than configuration flags you can add later.
- Do event loops propagate OpenTelemetry context automatically?
- No. Event loops must restore the original context when executing callbacks, so you have to wrap each callback using a documented bindContext pattern that captures Context::getCurrent(), activates it inside the wrapper, and detaches it in a finally block. This is high effort but low ambiguity work, and it should be budgeted as instrumentation engineering rather than treated as a configuration toggle. Avoid keeping unnecessary references to arguments in those wrappers.
- How do I prevent context leaking between Laravel requests and queued jobs?
- Keep debug scopes enabled in development and staging so missing detach() calls surface as warnings, and make the activate-then-detach-in-finally pattern a code review checklist item. Wrap the boundaries, such as middleware and job decorators, so each request or job starts and ends with a clean context. If your application uses exit or die, prefer fixing those call sites over disabling debug scopes globally.
- Which PHP versions does open-telemetry/context support and is it actively maintained?
- The PHP floor is not reliably stated in the split package metadata: release notes show PHP 7.4 and 8.0 dropped, one summary claims 8.1+, while monorepo agent guidance states PHP 8.2 is the minimum and default. Confirm the floor empirically against the tag you pin before planning an upgrade path. Also ignore the stale last-release date in the metadata, since release notes include 1.5.0 and monorepo guidance references PHP 8.5 testing; track the monorepo tags and its SDK compatibility matrix instead. The zero listed dependents is a false signal from subtree splitting, so judge adoption by the SDK rather than this counter.
Weaver
How can I help you explore Laravel packages today?