feat: add Webhook component integration

Author: Jean-Beru

composer-dependency-analyser.php

@@ -13,9 +13,15 @@
     ->addPathToScan(__DIR__.'/src/Debug', isDev: true)
     ->addPathToScan(__DIR__.'/tests', isDev: true)
 
+    ->ignoreErrorsOnPackage('symfony/remote-event', [
+        ErrorType::DEV_DEPENDENCY_IN_PROD,
+    ])
     ->ignoreErrorsOnPackage('symfony/routing', [
         ErrorType::DEV_DEPENDENCY_IN_PROD,
     ])
+    ->ignoreErrorsOnPackage('symfony/webhook', [
+        ErrorType::DEV_DEPENDENCY_IN_PROD,
+    ])
     ->ignoreErrorsOnPackage('twig/twig', [
         ErrorType::DEV_DEPENDENCY_IN_PROD,
     ])

composer.json

@@ -42,10 +42,12 @@
         "symfony/framework-bundle": "^6.4 || ^7.0",
         "symfony/http-client": "^6.4 || ^7.0",
         "symfony/monolog-bundle": "^3.10",
+        "symfony/remote-event": "^6.4 || ^7.0",
         "symfony/routing": "^6.4 || ^7.0",
         "symfony/stopwatch": "^6.4 || ^7.0",
         "symfony/twig-bundle": "^6.4 || ^7.0",
         "symfony/var-dumper": "^6.4 || ^7.0",
+        "symfony/webhook": "^6.4 || ^7.0",
         "twig/twig": "^3.14"
     },
     "config": {
@@ -56,7 +58,9 @@
     },
     "suggest": {
         "symfony/monolog-bundle": "Enables logging througout the generating process.",
-        "symfony/twig-bundle": "Allows you to use Twig to render templates into PDF",
+        "symfony/remote-event": "Allows you to use Webhook to handle asynchronous generation.",
+        "symfony/twig-bundle": "Allows you to use Twig to render templates into PDF.",
+        "symfony/webhook": "Allows you to use Webhook to handle asynchronous generation.",
         "monolog/monolog": "Enables logging througout the generating process."
     }
 }

config/builder_pdf.php

@@ -23,6 +23,7 @@
             service('sensiolabs_gotenberg.asset.base_dir_formatter'),
             service('.sensiolabs_gotenberg.webhook_configuration_registry'),
             service('request_stack'),
+            service('router')->nullOnInvalid(),
             service('twig')->nullOnInvalid(),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])
@@ -36,8 +37,8 @@
             service('sensiolabs_gotenberg.asset.base_dir_formatter'),
             service('.sensiolabs_gotenberg.webhook_configuration_registry'),
             service('request_stack'),
-            service('twig')->nullOnInvalid(),
             service('router')->nullOnInvalid(),
+            service('twig')->nullOnInvalid(),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])
         ->call('setRequestContext', [service('.sensiolabs_gotenberg.request_context')->nullOnInvalid()])
@@ -51,6 +52,7 @@
             service('sensiolabs_gotenberg.asset.base_dir_formatter'),
             service('.sensiolabs_gotenberg.webhook_configuration_registry'),
             service('request_stack'),
+            service('router')->nullOnInvalid(),
             service('twig')->nullOnInvalid(),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])

config/builder_screenshot.php

@@ -20,6 +20,7 @@
             service('sensiolabs_gotenberg.asset.base_dir_formatter'),
             service('.sensiolabs_gotenberg.webhook_configuration_registry'),
             service('request_stack'),
+            service('router')->nullOnInvalid(),
             service('twig')->nullOnInvalid(),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])
@@ -33,8 +34,8 @@
             service('sensiolabs_gotenberg.asset.base_dir_formatter'),
             service('.sensiolabs_gotenberg.webhook_configuration_registry'),
             service('request_stack'),
-            service('twig')->nullOnInvalid(),
             service('router')->nullOnInvalid(),
+            service('twig')->nullOnInvalid(),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])
         ->call('setRequestContext', [service('.sensiolabs_gotenberg.request_context')->nullOnInvalid()])
@@ -48,6 +49,7 @@
             service('sensiolabs_gotenberg.asset.base_dir_formatter'),
             service('.sensiolabs_gotenberg.webhook_configuration_registry'),
             service('request_stack'),
+            service('router')->nullOnInvalid(),
             service('twig')->nullOnInvalid(),
         ])
         ->call('setLogger', [service('logger')->nullOnInvalid()])

docs/async/webhook.md

@@ -0,0 +1,48 @@
+## Using the Symfony Webhook component
+
+Symfony provides a specific [Webhook component](https://symfony.com/doc/current/webhook.html) dedicated to this task.
+
+Its role is to parse requests related to known webhooks and dispatch a corresponding remote event. Then, this event can
+be handled by your application through the [Messenger component](https://symfony.com/doc/current/messenger.html).
+
+The GotenbergBundle offers a native integration of this component if installed.
+
+### Usage
+
+To connect the provider to your application, you need to configure the Webhook component routing:
+
+```yaml
+# config/packages/webhook.yaml
+framework:
+  webhook:
+    routing:
+      gotenberg:
+        service: 'sensiolabs_gotenberg.webhook.request_parser'
+```
+
+Then, create your handler to respond to the Gotenberg RemoteEvent:
+
+```php
+use Sensiolabs\GotenbergBundle\RemoteEvent\ErrorGotenbergEvent;
+use Sensiolabs\GotenbergBundle\RemoteEvent\SuccessGotenbergEvent;
+use Symfony\Component\RemoteEvent\Consumer\ConsumerInterface;
+use Symfony\Component\RemoteEvent\Attribute\AsRemoteEventConsumer;
+use Symfony\Component\RemoteEvent\RemoteEvent;
+
+#[AsRemoteEventConsumer('gotenberg')]
+class WebhookListener implements ConsumerInterface
+{
+    public function consume(RemoteEvent $event): void
+    {
+        if ($event instanceof SuccessGotenbergEvent) {
+            // Handle the event
+            // PDF content is available as a resource through the getFile() method
+        } elseif ($event instanceof ErrorGotenbergEvent) {
+            // Handle the error
+        }
+    }
+}
+```
+
+> [!WARNING]  
+> The webhook component **won't be used** if a [native webhook configuration](native.md) is set.

docs/webhook.md

@@ -1,3 +1,4 @@
 # Going async
 
 * [Native](./async/native.md)
+* [Using the Symfony Webhook component](./async/webhook.md)

src/Builder/AsyncBuilderTrait.php

@@ -2,8 +2,9 @@
 
 namespace Sensiolabs\GotenbergBundle\Builder;
 
-use Sensiolabs\GotenbergBundle\Exception\MissingRequiredFieldException;
+use Sensiolabs\GotenbergBundle\Exception\WebhookConfigurationException;
 use Sensiolabs\GotenbergBundle\Webhook\WebhookConfigurationRegistryInterface;
+use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
 
 trait AsyncBuilderTrait
 {
@@ -30,16 +31,22 @@ trait AsyncBuilderTrait
 
     private WebhookConfigurationRegistryInterface $webhookConfigurationRegistry;
 
+    protected UrlGeneratorInterface|null $urlGenerator;
+
     public function generateAsync(): void
     {
-        if (null === $this->successWebhookUrl) {
-            throw new MissingRequiredFieldException('->webhookUrl() was never called.');
-        }
+        $successWebhookUrl = $this->successWebhookUrl;
+        if (!$successWebhookUrl) {
+            if (!$this->urlGenerator) {
+                throw new WebhookConfigurationException(\sprintf('A webhook URL or Router is required to use "%s" method. Set the URL or try to run "composer require symfony/routing".', __METHOD__));
+            }
 
-        $errorWebhookUrl = $this->errorWebhookUrl ?? $this->successWebhookUrl;
+            $successWebhookUrl = $this->urlGenerator->generate('_webhook_controller', ['type' => 'gotenberg'], UrlGeneratorInterface::ABSOLUTE_URL);
+        }
+        $errorWebhookUrl = $this->errorWebhookUrl ?? $successWebhookUrl;
 
         $headers = [
-            'Gotenberg-Webhook-Url' => $this->successWebhookUrl,
+            'Gotenberg-Webhook-Url' => $successWebhookUrl,
             'Gotenberg-Webhook-Error-Url' => $errorWebhookUrl,
         ];
 
@@ -59,6 +66,7 @@ public function generateAsync(): void
             // Gotenberg will add the extension to the file name (e.g. filename : "file.pdf" => generated file : "file.pdf.pdf").
             $headers['Gotenberg-Output-Filename'] = $this->fileName;
         }
+
         $this->client->call($this->getEndpoint(), $this->getMultipartFormData(), $headers);
     }
 

src/Builder/Pdf/AbstractChromiumPdfBuilder.php

@@ -19,6 +19,7 @@
 use Symfony\Component\HttpFoundation\RequestStack;
 use Symfony\Component\Mime\Part\DataPart;
 use Symfony\Component\Mime\Part\File as DataPartFile;
+use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
 use Twig\Environment;
 
 abstract class AbstractChromiumPdfBuilder extends AbstractPdfBuilder
@@ -30,9 +31,10 @@ public function __construct(
         AssetBaseDirFormatter $asset,
         WebhookConfigurationRegistryInterface $webhookConfigurationRegistry,
         private readonly RequestStack $requestStack,
+        UrlGeneratorInterface|null $urlGenerator = null,
         private readonly Environment|null $twig = null,
     ) {
-        parent::__construct($gotenbergClient, $asset, $webhookConfigurationRegistry);
+        parent::__construct($gotenbergClient, $asset, $webhookConfigurationRegistry, $urlGenerator);
 
         $normalizers = [
             'extraHttpHeaders' => function (mixed $value): array {

src/Builder/Pdf/AbstractPdfBuilder.php

@@ -9,6 +9,7 @@
 use Sensiolabs\GotenbergBundle\Client\GotenbergClientInterface;
 use Sensiolabs\GotenbergBundle\Formatter\AssetBaseDirFormatter;
 use Sensiolabs\GotenbergBundle\Webhook\WebhookConfigurationRegistryInterface;
+use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
 
 abstract class AbstractPdfBuilder implements PdfBuilderInterface, AsyncBuilderInterface
 {
@@ -20,10 +21,12 @@ public function __construct(
         GotenbergClientInterface $gotenbergClient,
         AssetBaseDirFormatter $asset,
         WebhookConfigurationRegistryInterface $webhookConfigurationRegistry,
+        UrlGeneratorInterface|null $urlGenerator = null,
     ) {
         $this->client = $gotenbergClient;
         $this->asset = $asset;
         $this->webhookConfigurationRegistry = $webhookConfigurationRegistry;
+        $this->urlGenerator = $urlGenerator;
 
         $this->normalizers = [
             'metadata' => function (mixed $value): array {

src/Builder/Pdf/UrlPdfBuilder.php

@@ -22,10 +22,10 @@ public function __construct(
         AssetBaseDirFormatter $asset,
         WebhookConfigurationRegistryInterface $webhookConfigurationRegistry,
         RequestStack $requestStack,
+        UrlGeneratorInterface|null $urlGenerator = null,
         Environment|null $twig = null,
-        private readonly UrlGeneratorInterface|null $urlGenerator = null,
     ) {
-        parent::__construct($gotenbergClient, $asset, $webhookConfigurationRegistry, $requestStack, $twig);
+        parent::__construct($gotenbergClient, $asset, $webhookConfigurationRegistry, $requestStack, $urlGenerator, $twig);
 
         $this->addNormalizer('route', $this->generateUrlFromRoute(...));
     }