feat (Event): Dispatch a new PreSendEnvelopeEvent before sending the …

…envelope to DocuSign (#119)

doc/events.md

@@ -15,6 +15,7 @@ namespace App\EventSubscriber;
 
 use DocusignBundle\EnvelopeBuilder;
 use DocusignBundle\Events\PreSignEvent;
+use DocusignBundle\Events\PreSendEnvelopeEvent;
 use DocusignBundle\Events\DocumentSignatureCompletedEvent;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
@@ -25,6 +26,7 @@ class PreSignSubscriber implements EventSubscriberInterface
         // return the subscribed events, their methods and priorities
         return [
             PreSignEvent::class => 'preSign',
+            PreSendEnvelopeEvent::class => 'preSendEnvelope',
             DocumentSignatureCompletedEvent::class => 'onDocumentSignatureCompleted'
         ];
     }
@@ -39,6 +41,16 @@ class PreSignSubscriber implements EventSubscriberInterface
         // $envelopeBuilder->setCallbackParameters();
         // ...
     }
+
+    public function preSendEnvelope(PreSendEnvelopeEvent $preSendEnvelope)
+    {
+        // Here you can manipulate the EnvelopeBuilder and do some adjustment to the envelope before being sent to DocuSign.
+        $envelopeBuilder = $preSendEnvelope->getEnvelopeBuilder();
+
+        // $envelopeDefinition = $envelopeBuilder->getEnvelopeDefinition([]);
+        // ...
+        // $envelopeBuilder->setEnvelopeDefinition($envelopeDefinition);
+    }
 
     public function onDocumentSignatureCompleted(DocumentSignatureCompletedEvent $documentSignatureCompleted)
     {

src/EnvelopeCreator/SendEnvelope.php

@@ -17,20 +17,24 @@
 use DocuSign\eSign\ApiClient;
 use DocuSign\eSign\Configuration;
 use DocusignBundle\EnvelopeBuilderInterface;
+use DocusignBundle\Events\PreSendEnvelopeEvent;
 use DocusignBundle\Grant\GrantInterface;
+use Symfony\Component\EventDispatcher\EventDispatcherInterface;
 use Symfony\Component\Routing\RouterInterface;
 
 final class SendEnvelope implements EnvelopeBuilderCallableInterface
 {
     public $grant;
     private $router;
     private $envelopeBuilder;
+    private $eventDispatcher;
 
-    public function __construct(EnvelopeBuilderInterface $envelopeBuilder, GrantInterface $grant, RouterInterface $router)
+    public function __construct(EnvelopeBuilderInterface $envelopeBuilder, GrantInterface $grant, RouterInterface $router, EventDispatcherInterface $eventDispatcher)
     {
         $this->grant = $grant;
         $this->router = $router;
         $this->envelopeBuilder = $envelopeBuilder;
+        $this->eventDispatcher = $eventDispatcher;
     }
 
     /**
@@ -45,6 +49,10 @@ public function __invoke(array $context = [])
         }
 
         $this->envelopeBuilder->setEnvelopesApi($this->setUpConfiguration());
+
+        $this->eventDispatcher->dispatch($preSendEnvelopeEvent = new PreSendEnvelopeEvent($this->envelopeBuilder));
+        $this->envelopeBuilder = $preSendEnvelopeEvent->getEnvelopeBuilder();
+
         $this->envelopeBuilder->setEnvelopeId($this->envelopeBuilder->getEnvelopesApi()->createEnvelope((string) $this->envelopeBuilder->getAccountId(), $this->envelopeBuilder->getEnvelopeDefinition())->getEnvelopeId());
     }
 

src/Events/PreSendEnvelopeEvent.php

@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * This file is part of the DocusignBundle.
+ *
+ * (c) Grégoire Hébert <gregoire@les-tilleuls.coop>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace DocusignBundle\Events;
+
+use DocusignBundle\EnvelopeBuilderInterface;
+use Symfony\Contracts\EventDispatcher\Event;
+
+class PreSendEnvelopeEvent extends Event
+{
+    private $envelopeBuilder;
+
+    public function __construct(EnvelopeBuilderInterface $envelopeBuilder)
+    {
+        $this->envelopeBuilder = $envelopeBuilder;
+    }
+
+    public function getEnvelopeBuilder(): EnvelopeBuilderInterface
+    {
+        return $this->envelopeBuilder;
+    }
+}

tests/EnvelopeCreator/SendEnvelopeTest.php

@@ -18,10 +18,12 @@
 use DocuSign\eSign\Model\EnvelopeSummary;
 use DocusignBundle\EnvelopeBuilderInterface;
 use DocusignBundle\EnvelopeCreator\SendEnvelope;
+use DocusignBundle\Events\PreSendEnvelopeEvent;
 use DocusignBundle\Grant\GrantInterface;
 use DocusignBundle\Tests\ProphecyTrait;
 use PHPUnit\Framework\TestCase;
 use Prophecy\Argument;
+use Symfony\Component\EventDispatcher\EventDispatcherInterface;
 use Symfony\Component\Routing\RouterInterface;
 
 class SendEnvelopeTest extends TestCase
@@ -33,6 +35,7 @@ class SendEnvelopeTest extends TestCase
     private $routerProphecyMock;
     private $envelopesApiProphecyMock;
     private $envelopeSummaryProphecyMock;
+    private $eventDispatcherProphecyMock;
 
     protected function setUp(): void
     {
@@ -41,6 +44,7 @@ protected function setUp(): void
         $this->routerProphecyMock = $this->prophesize(RouterInterface::class);
         $this->envelopesApiProphecyMock = $this->prophesize(EnvelopesApi::class);
         $this->envelopeSummaryProphecyMock = $this->prophesize(EnvelopeSummary::class);
+        $this->eventDispatcherProphecyMock = $this->prophesize(EventDispatcherInterface::class);
     }
 
     public function testItCreatesASendEnvelope(): void
@@ -62,7 +66,9 @@ public function testItCreatesASendEnvelope(): void
         $this->envelopeBuilderProphecyMock->setEnvelopesApi(Argument::type(EnvelopesApi::class))->shouldBeCalled();
         $this->envelopeBuilderProphecyMock->setEnvelopeId('envelopeId')->shouldBeCalled();
 
-        $sendEnvelope = new SendEnvelope($this->envelopeBuilderProphecyMock->reveal(), $this->grantProphecyMock->reveal(), $this->routerProphecyMock->reveal(), 'default');
+        $this->eventDispatcherProphecyMock->dispatch(Argument::Type(PreSendEnvelopeEvent::class))->shouldBeCalled();
+
+        $sendEnvelope = new SendEnvelope($this->envelopeBuilderProphecyMock->reveal(), $this->grantProphecyMock->reveal(), $this->routerProphecyMock->reveal(), $this->eventDispatcherProphecyMock->reveal());
         $sendEnvelope(['signature_name' => 'default']);
     }
 }