Merge pull request #70 from joesexton00/feature/return-event-improvement

Include request and response in the ReturnEvent

docs/annotations.md

@@ -79,7 +79,7 @@ different variable name using the `var=` parameter on this annotation.
 
 `@QueryMap`
 -----------
-Query parameter appended to the URL.
+Associative array of query parameters to append to the URL.
 
 Values are converted to strings and then URL encoded.
 
@@ -88,18 +88,10 @@ Simple Example:
 ```php
 /**
  * @GET("/list")
- * @Query("page")
+ * @QueryMap("parameters")
  */
 ```
 
-If the variable name differs from the desired part name, you may specify a
-different variable name using the `var=` parameter on this annotation. 
-
-```php
-/**
- * @Query("page", var="inputPage")
- */
-```
 
 `@Returns`
 ----------

docs/usage.md

@@ -301,23 +301,29 @@ to Retrofit.
 
 ### BeforeSendEvent
 
-Retrofit will dispatch a `retrofit.beforeSend` event before a request is made.  It includes:
+Retrofit will dispatch a `retrofit.beforeSend` event before a request is made.  It includes the request and allows modifying the request before sending.
 
-- The request method
-- The request url
-- Any request headers
-- A request body
+    @see \Tebru\Retrofit\Event\BeforeSendEvent
 
 ### AfterSendEvent
 
-Similarly, a `retrofit.afterSend` event will be dispatched after a request has been completed. It
-only includes the response body.
+Similarly, a `retrofit.afterSend` event will be dispatched after a request has been completed. It includes the request and response, and allows modifying the response before deserializing.
+
+    @see \Tebru\Retrofit\Event\AfterSendEvent
+
+### ReturnEvent
+
+Just prior to returning, a `retrofit.return` event will be dispatched. It includes the data to return, the request, and the response. It is possible to modify the returned data using this event.
+
+    @see \Tebru\Retrofit\Event\ReturnEvent
 
 ### ApiExceptionEvent
 
 If the http client throws an exception, it will be caught and a `retrofit.apiException` event will be
 dispatched.  Additionally, a new `RetrofitApiException` will be thrown.
 
+    @see \Tebru\Retrofit\Event\ApiExceptionEvent
+
 Exceptions
 ----------
 

src/Event/ReturnEvent.php

@@ -6,6 +6,8 @@
 
 namespace Tebru\Retrofit\Event;
 
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
 use Symfony\Component\EventDispatcher\Event;
 
 /**
@@ -24,14 +26,32 @@ class ReturnEvent extends Event
      */
     private $return;
 
+    /**
+     * The request sent to the client
+     *
+     * @var RequestInterface
+     */
+    private $request;
+
+    /**
+     * The response from the client
+     *
+     * @var ResponseInterface
+     */
+    private $response;
+
     /**
      * Constructor
      *
      * @param mixed $return
+     * @param RequestInterface|null $request
+     * @param ResponseInterface|null $response
      */
-    public function __construct($return)
+    public function __construct($return, RequestInterface $request = null, ResponseInterface $response = null)
     {
         $this->return = $return;
+        $this->request = $request;
+        $this->response = $response;
     }
 
     /**
@@ -53,4 +73,24 @@ public function setReturn($return)
     {
         $this->return = $return;
     }
+
+    /**
+     * Get the request
+     *
+     * @return RequestInterface|null
+     */
+    public function getRequest()
+    {
+        return $this->request;
+    }
+
+    /**
+     * Get the response
+     *
+     * @return ResponseInterface|null
+     */
+    public function getResponse()
+    {
+        return $this->response;
+    }
 }

src/Generation/Handler/ReturnHandler.php

@@ -33,12 +33,12 @@ public function __invoke(HandlerContext $context)
         if ($callback !== null) {
             if ($context->annotations()->isCallbackOptional()) {
                 $context->body()->add('if (%s !== null) {', $callback);
-                $context->body()->add('$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent(null);');
+                $context->body()->add('$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent(null, $request, $response);');
                 $context->body()->add('$this->eventDispatcher->dispatch("retrofit.return", $returnEvent);');
                 $context->body()->add('return $returnEvent->getReturn();');
                 $context->body()->add('}');
             } else {
-                $context->body()->add('$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent(null);');
+                $context->body()->add('$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent(null, $request, $response);');
                 $context->body()->add('$this->eventDispatcher->dispatch("retrofit.return", $returnEvent);');
                 $context->body()->add('return $returnEvent->getReturn();');
 
@@ -76,7 +76,7 @@ public function __invoke(HandlerContext $context)
             $context->body()->add('$return = $retrofitResponse->body();');
         }
 
-        $context->body()->add('$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return);');
+        $context->body()->add('$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return, $request, $response);');
         $context->body()->add('$this->eventDispatcher->dispatch("retrofit.return", $returnEvent);');
         $context->body()->add('return $returnEvent->getReturn();');
     }

tests/Unit/Event/ReturnEventTest.php

@@ -6,6 +6,10 @@
 
 namespace Tebru\Retrofit\Test\Unit\Event;
 
+use GuzzleHttp\Psr7\Request;
+use GuzzleHttp\Psr7\Response;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
 use Tebru\Retrofit\Event\ReturnEvent;
 use Tebru\Retrofit\Test\MockeryTestCase;
 
@@ -18,13 +22,15 @@ class ReturnEventTest extends MockeryTestCase
 {
     public function testGetters()
     {
-        $event = new ReturnEvent('return');
+        $event = new ReturnEvent('return', new Request('GET', 'http://mockservice.com/get'), new Response());
         $this->assertSame('return', $event->getReturn());
+        $this->assertInstanceOf(RequestInterface::class, $event->getRequest());
+        $this->assertInstanceOf(ResponseInterface::class, $event->getResponse());
     }
 
     public function testSetters()
     {
-        $event = new ReturnEvent('return');
+        $event = new ReturnEvent('return', new Request('GET', 'http://mockservice.com/get'), new Response());
         $event->setReturn('return2');
         $this->assertSame('return2', $event->getReturn());
     }

tests/resources/generation/testReturnAsyncNotOptional.php

@@ -1,5 +1,5 @@
 <?php
 
-$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent(null);
+$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent(null, $request, $response);
 $this->eventDispatcher->dispatch('retrofit.return', $returnEvent);
 return $returnEvent->getReturn();

tests/resources/generation/testReturnAsyncOptional.php

@@ -1,12 +1,12 @@
 <?php
 
 if ($callback !== null) {
-    $returnEvent = new \Tebru\Retrofit\Event\ReturnEvent(null);
+    $returnEvent = new \Tebru\Retrofit\Event\ReturnEvent(null, $request, $response);
     $this->eventDispatcher->dispatch('retrofit.return', $returnEvent);
     return $returnEvent->getReturn();
 }
 $retrofitResponse = new \Tebru\Retrofit\Http\Response($response, 'array', $this->deserializerAdapter, array());
 $return = $retrofitResponse->body();
-$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return);
+$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return, $request, $response);
 $this->eventDispatcher->dispatch('retrofit.return', $returnEvent);
 return $returnEvent->getReturn();

tests/resources/generation/testReturnSyncArray.php

@@ -2,6 +2,6 @@
 
 $retrofitResponse = new \Tebru\Retrofit\Http\Response($response, 'array', $this->deserializerAdapter, array());
 $return = $retrofitResponse->body();
-$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return);
+$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return, $request, $response);
 $this->eventDispatcher->dispatch('retrofit.return', $returnEvent);
 return $returnEvent->getReturn();

tests/resources/generation/testReturnSyncContext.php

@@ -2,6 +2,6 @@
 
 $retrofitResponse = new \Tebru\Retrofit\Http\Response($response, 'array', $this->deserializerAdapter, array());
 $return = $retrofitResponse->body();
-$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return);
+$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return, $request, $response);
 $this->eventDispatcher->dispatch('retrofit.return', $returnEvent);
 return $returnEvent->getReturn();

tests/resources/generation/testReturnSyncObject.php

@@ -2,6 +2,6 @@
 
 $retrofitResponse = new \Tebru\Retrofit\Http\Response($response, 'Tebru\\Retrofit\\Test\\Mock\\MockUser', $this->deserializerAdapter, array());
 $return = $retrofitResponse->body();
-$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return);
+$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return, $request, $response);
 $this->eventDispatcher->dispatch('retrofit.return', $returnEvent);
 return $returnEvent->getReturn();

tests/resources/generation/testReturnSyncRaw.php

@@ -2,6 +2,6 @@
 
 $retrofitResponse = new \Tebru\Retrofit\Http\Response($response, 'raw', $this->deserializerAdapter, array());
 $return = $retrofitResponse;
-$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return);
+$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return, $request, $response);
 $this->eventDispatcher->dispatch('retrofit.return', $returnEvent);
 return $returnEvent->getReturn();

tests/resources/generation/testReturnSyncResponse.php

@@ -2,6 +2,6 @@
 
 $retrofitResponse = new \Tebru\Retrofit\Http\Response($response, 'Tebru\\Retrofit\\Test\\Mock\\MockUser', $this->deserializerAdapter, array());
 $return = $retrofitResponse;
-$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return);
+$returnEvent = new \Tebru\Retrofit\Event\ReturnEvent($return, $request, $response);
 $this->eventDispatcher->dispatch('retrofit.return', $returnEvent);
 return $returnEvent->getReturn();