feat(mailer): send Symfony Mailer email through PostHog with posthog+api://

.changeset/symfony-mailer-transport.md

@@ -0,0 +1,5 @@
+---
+"posthog-php": minor
+---
+
+Send Symfony Mailer email through PostHog: set `MAILER_DSN=posthog+api://<project secret key>@default` and register `PostHog\Mailer\PostHogTransportFactory`. Rendered emails, attachments, inline images, and the PostHog options (distinct ID, template key, idempotency key, engagement capture, sensitive) map to a transactional send, and an email PostHog cannot carry is refused before any request. Sends go through the app's `http_client` service when it has one. Symfony's `X-Track` header sets which opens and clicks PostHog tracks. On Symfony Mailer 8.2, a `RemoteTemplateEmail` sends a PostHog template. `EmailError::isRetryable()` is now public.

.github/workflows/php.yml

@@ -117,6 +117,58 @@ jobs:
         if: needs.detect-markdown-only.outputs.markdown_only != 'true'
         run: python3 -m unittest discover -s sdk_compliance_adapter -v
 
+  symfony-mailer:
+    needs: detect-markdown-only
+    if: needs.detect-markdown-only.outputs.markdown_only != 'true'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # The lock tests Symfony Mailer 7.4; these cover the oldest and newest supported lines.
+          - php-version: "8.2"
+            symfony: "6.4.*"
+            stability: stable
+          # The first 6.4 release: before 6.4.37, Symfony renames inline parts when it builds the body.
+          # Composer blocks it for security advisories, which don't apply to a test run.
+          - php-version: "8.2"
+            symfony: "6.4.0"
+            stability: stable
+            allow-insecure: true
+          # Symfony Mailer 8.2 adds remote templates; move to stable once 8.2.0 ships.
+          - php-version: "8.4"
+            symfony: "8.2.*"
+            stability: beta
+    name: symfony-mailer (${{ matrix.symfony }})
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up PHP ${{ matrix.php-version }}
+        uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # v2.40.0
+        with:
+          php-version: ${{ matrix.php-version }}
+          extensions: zlib
+          tools: composer
+
+      - name: Install Symfony ${{ matrix.symfony }}
+        env:
+          SYMFONY: ${{ matrix.symfony }}
+          STABILITY: ${{ matrix.stability }}
+          ALLOW_INSECURE: ${{ matrix.allow-insecure || 'false' }}
+        run: |
+          composer config minimum-stability "$STABILITY"
+          if [ "$ALLOW_INSECURE" = "true" ]; then composer config policy.advisories.block false; fi
+          composer config prefer-stable true
+          composer require --dev --no-update "symfony/mailer:$SYMFONY" "symfony/mime:$SYMFONY" "symfony/framework-bundle:$SYMFONY" "symfony/http-client:$SYMFONY"
+          composer update --with-all-dependencies --prefer-dist --no-progress
+
+      # Apps that deploy with an authoritative classmap load only the classes Composer found.
+      - name: Use an authoritative classmap
+        run: composer dump-autoload --classmap-authoritative
+
+      - name: Run the Symfony Mailer tests
+        run: ./vendor/bin/phpunit --bootstrap vendor/autoload.php --configuration phpunit.xml --no-coverage test/Mailer
+
   coverage:
     runs-on: ubuntu-latest
     needs:

api/public-api.json

@@ -1843,6 +1843,13 @@
                     "final": false,
                     "returnType": "?string",
                     "parameters": []
+                },
+                "isRetryable": {
+                    "static": false,
+                    "abstract": false,
+                    "final": false,
+                    "returnType": "bool",
+                    "parameters": []
                 }
             }
         },
@@ -4155,6 +4162,204 @@
                 }
             }
         },
+        "PostHog\\Mailer\\PostHogTransport": {
+            "type": "class",
+            "abstract": false,
+            "final": true,
+            "readonly": false,
+            "extends": "Symfony\\Component\\Mailer\\Transport\\AbstractTransport",
+            "implements": [
+                "PostHog\\Internal\\Mailer\\RemoteTemplateSupport",
+                "Stringable",
+                "Symfony\\Component\\Mailer\\Transport\\TransportInterface"
+            ],
+            "constants": {
+                "INTEGRATION": {
+                    "type": "string",
+                    "value": "posthog-php-mailer"
+                }
+            },
+            "properties": [],
+            "methods": {
+                "__construct": {
+                    "static": false,
+                    "abstract": false,
+                    "final": false,
+                    "returnType": null,
+                    "parameters": [
+                        {
+                            "name": "emails",
+                            "type": "PostHog\\Emails",
+                            "byReference": false,
+                            "variadic": false,
+                            "optional": false,
+                            "default": null,
+                            "defaultConstant": null,
+                            "hasDefault": false
+                        },
+                        {
+                            "name": "integration",
+                            "type": "?string",
+                            "byReference": false,
+                            "variadic": false,
+                            "optional": true,
+                            "default": null,
+                            "defaultConstant": null,
+                            "hasDefault": true
+                        },
+                        {
+                            "name": "defaultTemplateKey",
+                            "type": "?string",
+                            "byReference": false,
+                            "variadic": false,
+                            "optional": true,
+                            "default": null,
+                            "defaultConstant": null,
+                            "hasDefault": true
+                        },
+                        {
+                            "name": "templates",
+                            "type": "bool",
+                            "byReference": false,
+                            "variadic": false,
+                            "optional": true,
+                            "default": true,
+                            "defaultConstant": null,
+                            "hasDefault": true
+                        },
+                        {
+                            "name": "dispatcher",
+                            "type": "?Psr\\EventDispatcher\\EventDispatcherInterface",
+                            "byReference": false,
+                            "variadic": false,
+                            "optional": true,
+                            "default": null,
+                            "defaultConstant": null,
+                            "hasDefault": true
+                        },
+                        {
+                            "name": "logger",
+                            "type": "?Psr\\Log\\LoggerInterface",
+                            "byReference": false,
+                            "variadic": false,
+                            "optional": true,
+                            "default": null,
+                            "defaultConstant": null,
+                            "hasDefault": true
+                        }
+                    ]
+                },
+                "__toString": {
+                    "static": false,
+                    "abstract": false,
+                    "final": false,
+                    "returnType": "string",
+                    "parameters": []
+                }
+            }
+        },
+        "PostHog\\Mailer\\PostHogTransportException": {
+            "type": "class",
+            "abstract": false,
+            "final": true,
+            "readonly": false,
+            "extends": "Symfony\\Component\\Mailer\\Exception\\TransportException",
+            "implements": [
+                "Stringable",
+                "Symfony\\Component\\Mailer\\Exception\\ExceptionInterface",
+                "Symfony\\Component\\Mailer\\Exception\\TransportExceptionInterface",
+                "Throwable"
+            ],
+            "constants": [],
+            "properties": [],
+            "methods": {
+                "__construct": {
+                    "static": false,
+                    "abstract": false,
+                    "final": false,
+                    "returnType": null,
+                    "parameters": [
+                        {
+                            "name": "error",
+                            "type": "PostHog\\EmailError",
+                            "byReference": false,
+                            "variadic": false,
+                            "optional": false,
+                            "default": null,
+                            "defaultConstant": null,
+                            "hasDefault": false
+                        }
+                    ]
+                },
+                "getErrorCode": {
+                    "static": false,
+                    "abstract": false,
+                    "final": false,
+                    "returnType": "string",
+                    "parameters": []
+                },
+                "getField": {
+                    "static": false,
+                    "abstract": false,
+                    "final": false,
+                    "returnType": "?string",
+                    "parameters": []
+                },
+                "getRetryAfter": {
+                    "static": false,
+                    "abstract": false,
+                    "final": false,
+                    "returnType": "?int",
+                    "parameters": []
+                },
+                "getStatusCode": {
+                    "static": false,
+                    "abstract": false,
+                    "final": false,
+                    "returnType": "?int",
+                    "parameters": []
+                },
+                "isRetryable": {
+                    "static": false,
+                    "abstract": false,
+                    "final": false,
+                    "returnType": "bool",
+                    "parameters": []
+                }
+            }
+        },
+        "PostHog\\Mailer\\PostHogTransportFactory": {
+            "type": "class",
+            "abstract": false,
+            "final": true,
+            "readonly": false,
+            "extends": "Symfony\\Component\\Mailer\\Transport\\AbstractTransportFactory",
+            "implements": [
+                "Symfony\\Component\\Mailer\\Transport\\TransportFactoryInterface"
+            ],
+            "constants": [],
+            "properties": [],
+            "methods": {
+                "create": {
+                    "static": false,
+                    "abstract": false,
+                    "final": false,
+                    "returnType": "Symfony\\Component\\Mailer\\Transport\\TransportInterface",
+                    "parameters": [
+                        {
+                            "name": "dsn",
+                            "type": "Symfony\\Component\\Mailer\\Transport\\Dsn",
+                            "byReference": false,
+                            "variadic": false,
+                            "optional": false,
+                            "default": null,
+                            "defaultConstant": null,
+                            "hasDefault": false
+                        }
+                    ]
+                }
+            }
+        },
         "PostHog\\OpenTelemetry\\ContextSpanProcessor": {
             "type": "class",
             "abstract": false,

composer.json

@@ -25,7 +25,13 @@
 		"squizlabs/php_codesniffer": "^4.0",
 		"ext-zlib": "*",
 		"open-telemetry/api": "^1.0",
-		"open-telemetry/sdk": "^1.0"
+		"open-telemetry/sdk": "^1.0",
+		"symfony/framework-bundle": "^6.4|^7.0|^8.0",
+		"symfony/http-client": "^6.4|^7.0|^8.0",
+		"symfony/mailer": "^6.4|^7.0|^8.0"
+	},
+	"suggest": {
+		"symfony/mailer": "Send Symfony Mailer email through PostHog with the posthog+api:// transport."
 	},
 	"autoload": {
 		"psr-4": {