From c8f7e22a89a2e9a1b73920da953dbc9cc5292943 Mon Sep 17 00:00:00 2001
From: jdeveloper <jdeveloper.inxenio@gmail.com>
Date: Thu, 21 May 2015 10:21:19 +0200
Subject: [PATCH] Documented AuthTokenUpdaterListener class

---
 EventListener/AuthTokenUpdaterListener.php | 26 ++++++++++++++++++++++
 README.md                                  |  2 ++
 2 files changed, 28 insertions(+)

diff --git a/EventListener/AuthTokenUpdaterListener.php b/EventListener/AuthTokenUpdaterListener.php
index 3d4810e..fd59102 100755
--- a/EventListener/AuthTokenUpdaterListener.php
+++ b/EventListener/AuthTokenUpdaterListener.php
@@ -8,6 +8,12 @@
 use Ant\ChateaClient\Service\Client\ChateaGratisAppClient;
 use Ant\Bundle\ChateaSecureBundle\Security\User\User;
 
+/**
+ * Request listener that updates the HTTP client access token of OAuth2 if an action requirs to be made by the loggedin user
+ * (action or class having @APIUser annotation)
+ * Class AuthTokenUpdaterListener
+ * @package Ant\Bundle\ChateaClientBundle\EventListener
+ */
 class AuthTokenUpdaterListener
 {
     private $annotationReader;
@@ -15,6 +21,12 @@ class AuthTokenUpdaterListener
     private $client;
     private $annotationClass = 'Ant\Bundle\ChateaClientBundle\Security\Authentication\Annotation\APIUser';
 
+    /**
+     * Constructor
+     * @param Reader $annotationReader
+     * @param SecurityContextInterface $securityContext
+     * @param ChateaGratisAppClient $client
+     */
     function __construct(Reader $annotationReader, SecurityContextInterface $securityContext, ChateaGratisAppClient $client)
     {
         $this->annotationReader = $annotationReader;
@@ -26,12 +38,18 @@ public function onKernelController(FilterControllerEvent $event)
     {
         $controller = $event->getController();
 
+        /**
+         * if the action has the APIUser annotation, check first if the user is valid and if so update the client acces token
+         */
         if($this->hasApiUserAnnotation($controller)){
             $this->assertUserIsLoggedIn();
             $this->updateClientAccessToken();
         }
     }
 
+    /**
+     * Asserts that a user is logged in
+     */
     private function assertUserIsLoggedIn()
     {
         $token = $this->securityContext->getToken();
@@ -45,6 +63,11 @@ private function assertUserIsLoggedIn()
         }
     }
 
+    /**
+     * Checks if the action or the hole controller has an @APIUser annotation
+     * @param $controller
+     * @return bool
+     */
     private function hasApiUserAnnotation($controller)
     {
         $object = new \ReflectionObject($controller[0]);
@@ -54,6 +77,9 @@ private function hasApiUserAnnotation($controller)
             $this->annotationReader->getClassAnnotation($object, $this->annotationClass) != null;
     }
 
+    /**
+     * Updates the access token of the HTTP client with the access token of the current user
+     */
     private function updateClientAccessToken()
     {
         $user = $this->securityContext->getToken()->getUser();
diff --git a/README.md b/README.md
index 8aabfe4..c3a7ffb 100755
--- a/README.md
+++ b/README.md
@@ -128,3 +128,5 @@ class AreaRestringidaController
     }
 }
 ```
+
+Dicha annotación es gestionada por el listener ```Ant\Bundle\ChateaClientBundle\EventListener\AuthTokenUpdaterListener``` que escucha al evento del controlador para averiguar si debe actualizar el access token del usuario en caso necesario.