feature: psr7 and symfony http foundation telemetry bridges (#2167)

* feature: psr7 and symfony http foundation telemetry bridges

- added: New flow-php/symfony-http-foundation-telemetry-bridge package
for Symfony HttpFoundation telemetry context propagation
- added: PHPStan generics support to Carrier interface
- added: Unified unwrap() method to all Carrier implementations
- added: Fluent chaining support for Carrier::set()
- changed: [BC] Carrier::set() return type changed from void to static
- changed: [BC] ArrayCarrier::toArray() replaced by unwrap()
- changed: [BC] ResponseCarrier::getResponse() replaced by unwrap()

* fix: regenerated dsl definitions

* fix: added missing psr7 bridge repo elements

Author: norberttech

.github/workflows/monorepo-split.yml

@@ -88,8 +88,12 @@ jobs:
             split_repository: 'monolog-telemetry-bridge'
           - local_path: 'src/bridge/openapi/specification'
             split_repository: 'openapi-specification-bridge'
+          - local_path: 'src/bridge/psr7/telemetry'
+            split_repository: 'psr7-telemetry-bridge'
           - local_path: 'src/bridge/symfony/http-foundation'
             split_repository: 'symfony-http-foundation-bridge'
+          - local_path: 'src/bridge/symfony/http-foundation-telemetry'
+            split_repository: 'symfony-http-foundation-telemetry-bridge'
           - local_path: 'src/bridge/telemetry/otlp'
             split_repository: 'telemetry-otlp-bridge'
 

bin/docs.php

@@ -67,6 +67,8 @@ public function execute(InputInterface $input, OutputInterface $output) : int
             __DIR__ . '/../src/bridge/filesystem/azure/src/Flow/Filesystem/Bridge/Azure/DSL/functions.php',
             __DIR__ . '/../src/bridge/filesystem/async-aws/src/Flow/Filesystem/Bridge/AsyncAWS/DSL/functions.php',
             __DIR__ . '/../src/bridge/monolog/telemetry/src/Flow/Bridge/Monolog/Telemetry/DSL/functions.php',
+            __DIR__ . '/../src/bridge/symfony/http-foundation-telemetry/src/Flow/Bridge/Symfony/HttpFoundationTelemetry/DSL/functions.php',
+            __DIR__ . '/../src/bridge/psr7/telemetry/src/Flow/Bridge/Psr7/Telemetry/DSL/functions.php',
             __DIR__ . '/../src/bridge/telemetry/otlp/src/Flow/Bridge/Telemetry/OTLP/DSL/functions.php',
         ];
 

composer.json

@@ -99,6 +99,8 @@
         "flow-php/postgresql": "self.version",
         "flow-php/snappy": "self.version",
         "flow-php/symfony-http-foundation-bridge": "self.version",
+        "flow-php/symfony-http-foundation-telemetry-bridge": "self.version",
+        "flow-php/psr7-telemetry-bridge": "self.version",
         "flow-php/telemetry": "self.version",
         "flow-php/telemetry-otlp-bridge": "self.version",
         "flow-php/types": "self.version"
@@ -128,7 +130,9 @@
                 "src/bridge/monolog/http/src/Flow",
                 "src/bridge/monolog/telemetry/src/Flow",
                 "src/bridge/openapi/specification/src/Flow",
+                "src/bridge/psr7/telemetry/src/Flow",
                 "src/bridge/symfony/http-foundation/src/Flow",
+                "src/bridge/symfony/http-foundation-telemetry/src/Flow",
                 "src/bridge/telemetry/otlp/src/Flow",
                 "src/cli/src/Flow",
                 "src/core/etl/src/Flow",
@@ -172,7 +176,9 @@
             "src/bridge/monolog/http/src/Flow/Bridge/Monolog/Http/DSL/functions.php",
             "src/bridge/monolog/telemetry/src/Flow/Bridge/Monolog/Telemetry/DSL/functions.php",
             "src/bridge/openapi/specification/src/Flow/Bridge/OpenAPI/Specification/DSL/functions.php",
+            "src/bridge/psr7/telemetry/src/Flow/Bridge/Psr7/Telemetry/DSL/functions.php",
             "src/bridge/symfony/http-foundation/src/Flow/Bridge/Symfony/HttpFoundation/functions.php",
+            "src/bridge/symfony/http-foundation-telemetry/src/Flow/Bridge/Symfony/HttpFoundationTelemetry/DSL/functions.php",
             "src/bridge/telemetry/otlp/src/Flow/Bridge/Telemetry/OTLP/DSL/functions.php",
             "src/cli/src/Flow/CLI/DSL/functions.php",
             "src/core/etl/src/Flow/ETL/DSL/functions.php",
@@ -212,7 +218,9 @@
                 "src/bridge/monolog/http/tests/Flow",
                 "src/bridge/monolog/telemetry/tests/Flow",
                 "src/bridge/openapi/specification/tests/Flow",
+                "src/bridge/psr7/telemetry/tests/Flow",
                 "src/bridge/symfony/http-foundation/tests/Flow",
+                "src/bridge/symfony/http-foundation-telemetry/tests/Flow",
                 "src/bridge/telemetry/otlp/tests/Flow",
                 "src/cli/tests/Flow",
                 "src/core/etl/tests/Flow",
@@ -281,7 +289,9 @@
             "@test:bridge:monolog-http",
             "@test:bridge:monolog-telemetry",
             "@test:bridge:openapi-specification",
+            "@test:bridge:psr7-telemetry",
             "@test:bridge:symfony-http-foundation",
+            "@test:bridge:symfony-http-foundation-telemetry",
             "@test:bridge:telemetry-otlp"
         ],
         "test:adapters": [
@@ -359,10 +369,18 @@
         "test:bridge:openapi-specification": [
             "tools/phpunit/vendor/bin/phpunit --testsuite=bridge-openapi-specification-unit --log-junit ./var/phpunit/logs/bridge-openapi-specification-unit.junit.xml --coverage-clover=./var/phpunit/coverage/clover/bridge-openapi-specification-unit.coverage.xml --coverage-html=./var/phpunit/coverage/html/bridge-openapi-specification-unit"
         ],
+        "test:bridge:psr7-telemetry": [
+            "tools/phpunit/vendor/bin/phpunit --testsuite=bridge-psr7-telemetry-unit --log-junit ./var/phpunit/logs/bridge-psr7-telemetry-unit.junit.xml --coverage-clover=./var/phpunit/coverage/clover/bridge-psr7-telemetry-unit.coverage.xml --coverage-html=./var/phpunit/coverage/html/bridge-psr7-telemetry-unit",
+            "tools/phpunit/vendor/bin/phpunit --testsuite=bridge-psr7-telemetry-integration --log-junit ./var/phpunit/logs/bridge-psr7-telemetry-integration.junit.xml --coverage-clover=./var/phpunit/coverage/clover/bridge-psr7-telemetry-integration.coverage.xml --coverage-html=./var/phpunit/coverage/html/bridge-psr7-telemetry-integration"
+        ],
         "test:bridge:symfony-http-foundation": [
             "tools/phpunit/vendor/bin/phpunit --testsuite=bridge-symfony-http-foundation-unit --log-junit ./var/phpunit/logs/bridge-symfony-http-foundation-unit.junit.xml --coverage-clover=./var/phpunit/coverage/clover/bridge-symfony-http-foundation-unit.coverage.xml --coverage-html=./var/phpunit/coverage/html/bridge-symfony-http-foundation-unit",
             "tools/phpunit/vendor/bin/phpunit --testsuite=bridge-symfony-http-foundation-integration --log-junit ./var/phpunit/logs/bridge-symfony-http-foundation-integration.junit.xml --coverage-clover=./var/phpunit/coverage/clover/bridge-symfony-http-foundation-integration.coverage.xml --coverage-html=./var/phpunit/coverage/html/bridge-symfony-http-foundation-integration"
         ],
+        "test:bridge:symfony-http-foundation-telemetry": [
+            "tools/phpunit/vendor/bin/phpunit --testsuite=bridge-symfony-http-foundation-telemetry-unit --log-junit ./var/phpunit/logs/bridge-symfony-http-foundation-telemetry-unit.junit.xml --coverage-clover=./var/phpunit/coverage/clover/bridge-symfony-http-foundation-telemetry-unit.coverage.xml --coverage-html=./var/phpunit/coverage/html/bridge-symfony-http-foundation-telemetry-unit",
+            "tools/phpunit/vendor/bin/phpunit --testsuite=bridge-symfony-http-foundation-telemetry-integration --log-junit ./var/phpunit/logs/bridge-symfony-http-foundation-telemetry-integration.junit.xml --coverage-clover=./var/phpunit/coverage/clover/bridge-symfony-http-foundation-telemetry-integration.coverage.xml --coverage-html=./var/phpunit/coverage/html/bridge-symfony-http-foundation-telemetry-integration"
+        ],
         "test:bridge:telemetry-otlp": [
             "tools/phpunit/vendor/bin/phpunit --testsuite=bridge-telemetry-otlp-unit --log-junit ./var/phpunit/logs/bridge-telemetry-otlp-unit.junit.xml --coverage-clover=./var/phpunit/coverage/clover/bridge-telemetry-otlp-unit.coverage.xml --coverage-html=./var/phpunit/coverage/html/bridge-telemetry-otlp-unit",
             "tools/phpunit/vendor/bin/phpunit --testsuite=bridge-telemetry-otlp-integration --log-junit ./var/phpunit/logs/bridge-telemetry-otlp-integration.junit.xml --coverage-clover=./var/phpunit/coverage/clover/bridge-telemetry-otlp-integration.coverage.xml --coverage-html=./var/phpunit/coverage/html/bridge-telemetry-otlp-integration"

documentation/components/bridges/psr7-telemetry-bridge.md

@@ -0,0 +1,102 @@
+# PSR-7 Telemetry Bridge
+
+Flow PSR-7 Telemetry Bridge provides carriers for propagators that can pass and read telemetry context
+and baggage via PSR-7 request and response objects.
+
+- [Back](/documentation/introduction.md)
+- [Packagist](https://packagist.org/packages/flow-php/psr7-telemetry-bridge)
+- [GitHub](https://github.com/flow-php/psr7-telemetry-bridge)
+
+[TOC]
+
+## Installation
+
+```
+composer require flow-php/psr7-telemetry-bridge:~--FLOW_PHP_VERSION--
+```
+
+## Overview
+
+This bridge connects Flow PHP's Telemetry library with PSR-7 compliant HTTP message implementations, enabling telemetry
+context propagation in HTTP-based applications. It provides carriers that allow propagators to inject and extract
+telemetry context (trace context, baggage) through HTTP headers in PSR-7 Request and Response objects.
+
+This is particularly useful for:
+
+- Distributed tracing across microservices
+- Propagating correlation IDs through HTTP calls
+- Passing baggage data (key-value pairs) across service boundaries
+- Integration with OpenTelemetry-based observability stacks
+- Framework-agnostic telemetry integration
+
+> **Note:** This bridge works with any PSR-7 compliant HTTP message implementation (Nyholm/PSR-7, Guzzle, Laminas, etc.).
+> Due to PSR-7's immutable nature, use `unwrap()` on the `ResponseCarrier` to retrieve the modified response after
+> injecting headers.
+
+## Requirements
+
+- PHP 8.3+
+- flow-php/telemetry
+- psr/http-message ^1.1 || ^2.0
+
+## Usage
+
+### Extracting context from incoming requests
+
+```php
+use Flow\Bridge\Psr7\Telemetry\RequestCarrier;
+use Flow\Telemetry\Propagation\CompositePropagator;
+use Flow\Telemetry\Propagation\W3CTraceContext;
+use Flow\Telemetry\Propagation\W3CBaggage;
+
+// Create propagator
+$propagator = new CompositePropagator([
+    new W3CTraceContext(),
+    new W3CBaggage(),
+]);
+
+// $request is a PSR-7 ServerRequestInterface
+$carrier = new RequestCarrier($request);
+$ctx = $propagator->extract($carrier);
+
+// Use extracted context
+if ($ctx->spanContext !== null) {
+    $traceId = $ctx->spanContext->traceId->toHex();
+    // ...
+}
+```
+
+### Injecting context into outgoing responses
+
+```php
+use Flow\Bridge\Psr7\Telemetry\ResponseCarrier;
+use Flow\Telemetry\Propagation\CompositePropagator;
+use Flow\Telemetry\Propagation\W3CTraceContext;
+use Flow\Telemetry\Propagation\W3CBaggage;
+use Flow\Telemetry\Propagation\PropagationContext;
+
+// Create propagator
+$propagator = new CompositePropagator([
+    new W3CTraceContext(),
+    new W3CBaggage(),
+]);
+
+// $response is a PSR-7 ResponseInterface
+$carrier = new ResponseCarrier($response);
+$propagator->inject($ctx, $carrier);
+
+// Get the modified response (PSR-7 responses are immutable)
+$response = $carrier->unwrap();
+```
+
+### DSL Functions
+
+The bridge provides convenient DSL functions:
+
+```php
+use function Flow\Bridge\Psr7\Telemetry\DSL\psr7_request_carrier;
+use function Flow\Bridge\Psr7\Telemetry\DSL\psr7_response_carrier;
+
+$requestCarrier = psr7_request_carrier($request);
+$responseCarrier = psr7_response_carrier($response);
+```

documentation/components/bridges/symfony-http-foundation-telemetry-bridge.md

@@ -0,0 +1,39 @@
+# Symfony HttpFoundation Telemetry Bridge
+
+Flow Symfony HttpFoundation Telemetry Bridge provides carriers for propagators that can pass and read telemetry context
+and baggage via Symfony HttpFoundation request and response objects.
+
+- [⬅️️ Back](/documentation/introduction.md)
+- [📦Packagist](https://packagist.org/packages/flow-php/symfony-http-foundation-telemetry-bridge)
+- [🐙GitHub](https://github.com/flow-php/symfony-http-foundation-telemetry-bridge)
+
+[TOC]
+
+## Installation
+
+```
+composer require flow-php/symfony-http-foundation-telemetry-bridge:~--FLOW_PHP_VERSION--
+```
+
+## Overview
+
+This bridge connects Flow PHP's Telemetry library with Symfony's HttpFoundation component, enabling telemetry context
+propagation in HTTP-based applications. It provides carriers that allow propagators to inject and extract telemetry
+context (trace context, baggage) through HTTP headers in Symfony Request and Response objects.
+
+This is particularly useful for:
+
+- Distributed tracing across microservices
+- Propagating correlation IDs through HTTP calls
+- Passing baggage data (key-value pairs) across service boundaries
+- Integration with OpenTelemetry-based observability stacks
+
+> **Note:** This bridge is separate from the `flow-php/symfony-http-foundation-bridge` which is designed for ETL
+> operations. This bridge focuses specifically on telemetry integration, allowing users who only need telemetry
+> support to avoid bringing in the entire ETL framework as a dependency.
+
+## Requirements
+
+- PHP 8.3+
+- flow-php/telemetry
+- symfony/http-foundation ^6.4 || ^7.3 || ^8.0

infection.json

@@ -8,6 +8,8 @@
       "src/lib/parquet/src",
       "src/lib/telemetry/src",
       "src/bridge/monolog/telemetry/src",
+      "src/bridge/psr7/telemetry/src",
+      "src/bridge/symfony/http-foundation-telemetry/src",
       "src/bridge/telemetry/otlp/src"
     ],
     "excludes": [
@@ -26,7 +28,9 @@
       "Flow/Telemetry/Provider/Void",
       "Flow/Telemetry/Provider/Console",
       "Flow/Bridge/Telemetry/OTLP/Exception",
-      "Flow/Bridge/Monolog/Telemetry/Exception"
+      "Flow/Bridge/Monolog/Telemetry/Exception",
+      "Flow/Bridge/Psr7/Telemetry/Exception",
+      "Flow/Bridge/Symfony/HttpFoundationTelemetry/Exception"
     ]
   },
   "logs": {

phpstan.neon

@@ -28,7 +28,9 @@ parameters:
         - src/bridge/monolog/http/src
         - src/bridge/monolog/telemetry/src
         - src/bridge/openapi/specification/src
+        - src/bridge/psr7/telemetry/src
         - src/bridge/symfony/http-foundation/src
+        - src/bridge/symfony/http-foundation-telemetry/src
         - src/bridge/telemetry/otlp/src
         - src/lib/array-dot/src
         - src/lib/azure-sdk/src
@@ -63,7 +65,9 @@ parameters:
         - src/bridge/monolog/http/tests
         - src/bridge/monolog/telemetry/tests
         - src/bridge/openapi/specification/tests
+        - src/bridge/psr7/telemetry/tests
         - src/bridge/symfony/http-foundation/tests
+        - src/bridge/symfony/http-foundation-telemetry/tests
         - src/bridge/telemetry/otlp/tests
         - src/lib/telemetry/tests
 

phpunit.xml.dist

@@ -116,6 +116,12 @@
         <testsuite name="bridge-openapi-specification-unit">
             <directory>src/bridge/openapi/specification/tests/Flow/Bridge/OpenAPI/Specification/Tests/Unit</directory>
         </testsuite>
+        <testsuite name="bridge-psr7-telemetry-unit">
+            <directory>src/bridge/psr7/telemetry/tests/Flow/Bridge/Psr7/Telemetry/Tests/Unit</directory>
+        </testsuite>
+        <testsuite name="bridge-psr7-telemetry-integration">
+            <directory>src/bridge/psr7/telemetry/tests/Flow/Bridge/Psr7/Telemetry/Tests/Integration</directory>
+        </testsuite>
         <testsuite name="bridge-symfony-http-foundation-unit">
             <directory>src/bridge/symfony/http-foundation/tests/Flow/Bridge/Symfony/HttpFoundation/Tests/Unit
             </directory>
@@ -124,6 +130,12 @@
             <directory>src/bridge/symfony/http-foundation/tests/Flow/Bridge/Symfony/HttpFoundation/Tests/Integration
             </directory>
         </testsuite>
+        <testsuite name="bridge-symfony-http-foundation-telemetry-unit">
+            <directory>src/bridge/symfony/http-foundation-telemetry/tests/Flow/Bridge/Symfony/HttpFoundationTelemetry/Tests/Unit</directory>
+        </testsuite>
+        <testsuite name="bridge-symfony-http-foundation-telemetry-integration">
+            <directory>src/bridge/symfony/http-foundation-telemetry/tests/Flow/Bridge/Symfony/HttpFoundationTelemetry/Tests/Integration</directory>
+        </testsuite>
         <testsuite name="bridge-telemetry-otlp-unit">
             <directory>src/bridge/telemetry/otlp/tests/Flow/Bridge/Telemetry/OTLP/Tests/Unit</directory>
         </testsuite>

src/bridge/psr7/telemetry/.gitattributes

@@ -0,0 +1,9 @@
+*.php text eol=lf
+
+/.github export-ignore
+/tests export-ignore
+
+/README.md export-ignore
+
+/.gitattributes export-ignore
+/.gitignore export-ignore

src/bridge/psr7/telemetry/.github/workflows/readonly.yaml

@@ -0,0 +1,17 @@
+name: Readonly
+
+on:
+  pull_request_target:
+    types: [opened]
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: superbrothers/close-pull-request@v3
+        with:
+          comment: |
+            Hi, thank you for your contribution.
+            Unfortunately, this repository is read-only. It's a split from our main monorepo repository.
+            In order to proceed with this PR please open it against https://github.com/flow-php/flow repository.
+            Thank you.