[HttpKernel] added missing phpdoc and tweaked existing ones

symfony · fabpot · Jan 11, 2013 · Dec 19, 2012 · Jan 3, 2013 · Jan 3, 2013
commit 403bb060ce45cc48df9b0ff299ba8f2aa53de21a
diff --git a/src/Symfony/Component/HttpKernel/Controller/ControllerReference.php b/src/Symfony/Component/HttpKernel/Controller/ControllerReference.php
@@ -12,16 +12,30 @@
 namespace Symfony\Component\HttpKernel\Controller;
 
 /**
- * ControllerReference.
+ * Acts as a marker and a data holder for a Controller.
+ *
+ * Some methods in Symfony accept both a URI (as a string) or a controller as
+ * an argument. In the latter case, instead of passing an array representing
+ * the controller, you can use an instance of this class.
  *
  * @author Fabien Potencier <fabien@symfony.com>
+ *
+ * @see Symfony\Component\HttpKernel\HttpContentRenderer
+ * @see Symfony\Component\HttpKernel\RenderingStrategy\RenderingStrategyInterface
  */
 class ControllerReference
 {
     public $controller;
     public $attributes = array();
     public $query = array();
 
+    /**
+     * Constructor.
+     *
+     * @param string $controller The controller name
+     * @param array  $attributes An array of parameters to add to the Request attributes
+     * @param array  $query      An array of parameters to add to the Request query string
+     */
     public function __construct($controller, array $attributes = array(), array $query = array())
     {
         $this->controller = $controller;

diff --git a/src/Symfony/Component/HttpKernel/EventListener/RouterProxyListener.php b/src/Symfony/Component/HttpKernel/EventListener/RouterProxyListener.php
@@ -22,7 +22,7 @@
 /**
  * Proxies URIs when the current route name is "_proxy".
  *
- * If the request does not come from a trusted, it throws an
+ * If the request does not come from a trusted IP, it throws an
  * AccessDeniedHttpException exception.
  *
  * @author Fabien Potencier <fabien@symfony.com>

diff --git a/src/Symfony/Component/HttpKernel/HttpContentRenderer.php b/src/Symfony/Component/HttpKernel/HttpContentRenderer.php
@@ -19,6 +19,7 @@
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
 /**
+ * Renders a URI using different strategies.
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
@@ -28,6 +29,12 @@ class HttpContentRenderer implements EventSubscriberInterface
     private $strategies;
     private $requests;
 
+    /**
+     * Constructor.
+     *
+     * @param RenderingStrategyInterface[] $strategies An array of RenderingStrategyInterface instances
+     * @param Boolean                      $debug      Whether the debug mode is enabled or not
+     */
     public function __construct(array $strategies = array(), $debug = false)
     {
         $this->strategies = array();
@@ -38,6 +45,11 @@ public function __construct(array $strategies = array(), $debug = false)
         $this->requests = array();
     }
 
+    /**
+     * Adds a rendering strategy.
+     *
+     * @param RenderingStrategyInterface $strategy A RenderingStrategyInterface instance
+     */
     public function addStrategy(RenderingStrategyInterface $strategy)
     {
         $this->strategies[$strategy->getName()] = $strategy;
@@ -66,13 +78,16 @@ public function onKernelResponse(FilterResponseEvent $event)
     /**
      * Renders a URI and returns the Response content.
      *
+     * When the Response is a StreamedResponse, the content is streamed immediately
+     * instead of being returned.
+     *
      *  * ignore_errors: true to return an empty string in case of an error
      *  * strategy:      the strategy to use for rendering
      *
      * @param string|ControllerReference $uri     A URI as a string or a ControllerReference instance
      * @param array                      $options An array of options
      *
-     * @return string The Response content
+     * @return string|null The Response content or null when the Response is streamed
      */
     public function render($uri, array $options = array())
     {
@@ -99,6 +114,7 @@ public static function getSubscribedEvents()
         );
     }
 
+    // to be removed in 2.3
     private function fixOptions($options)
     {
         // support for the standalone option is @deprecated in 2.2 and replaced with the strategy option

diff --git a/src/Symfony/Component/HttpKernel/RenderingStrategy/DefaultRenderingStrategy.php b/src/Symfony/Component/HttpKernel/RenderingStrategy/DefaultRenderingStrategy.php
@@ -16,18 +16,27 @@
 use Symfony\Component\HttpKernel\Controller\ControllerReference;
 
 /**
+ * Implements the default rendering strategy where the Request is rendered by the current HTTP kernel.
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
 class DefaultRenderingStrategy extends GeneratorAwareRenderingStrategy
 {
     private $kernel;
 
+    /**
+     * Constructor.
+     *
+     * @param HttpKernelInterface $kernel A HttpKernelInterface instance
+     */
     public function __construct(HttpKernelInterface $kernel)
     {
         $this->kernel = $kernel;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function render($uri, Request $request = null, array $options = array())
     {
         if ($uri instanceof ControllerReference) {
@@ -94,6 +103,9 @@ protected function createSubRequest($uri, Request $request = null)
         return $subRequest;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getName()
     {
         return 'default';

diff --git a/src/Symfony/Component/HttpKernel/RenderingStrategy/EsiRenderingStrategy.php b/src/Symfony/Component/HttpKernel/RenderingStrategy/EsiRenderingStrategy.php
@@ -16,6 +16,7 @@
 use Symfony\Component\HttpKernel\HttpCache\Esi;
 
 /**
+ * Implements the ESI rendering strategy.
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
@@ -24,22 +25,34 @@ class EsiRenderingStrategy extends GeneratorAwareRenderingStrategy
     private $esi;
     private $defaultStrategy;
 
+    /**
+     * Constructor.
+     *
+     * The "fallback" strategy when ESI is not available should always be an
+     * instance of DefaultRenderingStrategy (or a class you are using for the
+     * default strategy).
+     *
+     * @param Esi                        $esi             An Esi instance
+     * @param RenderingStrategyInterface $defaultStrategy The default strategy to use when ESI is not supported
+     */
     public function __construct(Esi $esi, RenderingStrategyInterface $defaultStrategy)
     {
         $this->esi = $esi;
         $this->defaultStrategy = $defaultStrategy;
     }
 
     /**
+     * {@inheritdoc}
      *
-     * Note that this method generates an esi:include tag only when both the standalone
-     * option is set to true and the request has ESI capability (@see Symfony\Component\HttpKernel\HttpCache\ESI).
+     * Note that if the current Request has no ESI capability, this method
+     * falls back to use the default rendering strategy.
      *
-     * Available options:
+     * Additional available options:
      *
-     *  * ignore_errors: true to return an empty string in case of an error
-     *  * alt: an alternative URI to execute in case of an error
+     *  * alt: an alternative URI to render in case of an error
      *  * comment: a comment to add when returning an esi:include tag
+     *
+     * @see Symfony\Component\HttpKernel\HttpCache\ESI
      */
     public function render($uri, Request $request = null, array $options = array())
     {
@@ -59,6 +72,9 @@ public function render($uri, Request $request = null, array $options = array())
         return $this->esi->renderIncludeTag($uri, $alt, $options['ignore_errors'], isset($options['comment']) ? $options['comment'] : '');
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getName()
     {
         return 'esi';

diff --git a/src/Symfony/Component/HttpKernel/RenderingStrategy/GeneratorAwareRenderingStrategy.php b/src/Symfony/Component/HttpKernel/RenderingStrategy/GeneratorAwareRenderingStrategy.php
@@ -17,13 +17,19 @@
 use Symfony\Component\Routing\Exception\RouteNotFoundException;
 
 /**
+ * Adds the possibility to generate a proxy URI for a given Controller.
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
 abstract class GeneratorAwareRenderingStrategy implements RenderingStrategyInterface
 {
     protected $generator;
 
+    /**
+     * Sets a URL generator to use for proxy URIs generation.
+     *
+     * @param UrlGeneratorInterface $generator An UrlGeneratorInterface instance
+     */
     public function setUrlGenerator(UrlGeneratorInterface $generator)
     {
         $this->generator = $generator;

diff --git a/src/Symfony/Component/HttpKernel/RenderingStrategy/HIncludeRenderingStrategy.php b/src/Symfony/Component/HttpKernel/RenderingStrategy/HIncludeRenderingStrategy.php
@@ -17,6 +17,7 @@
 use Symfony\Component\HttpKernel\UriSigner;
 
 /**
+ * Implements the Hinclude rendering strategy.
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
@@ -26,6 +27,13 @@ class HIncludeRenderingStrategy extends GeneratorAwareRenderingStrategy
     private $globalDefaultTemplate;
     private $signer;
 
+    /**
+     * Constructor.
+     *
+     * @param EngineInterface|\Twig_Environment $templating            An EngineInterface or a \Twig_Environment instance
+     * @param UriSigner                         $signer                A UriSigner instance
+     * @param string                            $globalDefaultTemplate The content of the global default template
+     */
     public function __construct($templating, UriSigner $signer = null, $globalDefaultTemplate = null)
     {
         if (!$templating instanceof EngineInterface && !$templating instanceof \Twig_Environment) {
@@ -37,6 +45,9 @@ public function __construct($templating, UriSigner $signer = null, $globalDefaul
         $this->signer = $signer;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function render($uri, Request $request = null, array $options = array())
     {
         if ($uri instanceof ControllerReference) {
@@ -95,6 +106,9 @@ private function templateExists($template)
         return false;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getName()
     {
         return 'hinclude';

diff --git a/src/Symfony/Component/HttpKernel/RenderingStrategy/RenderingStrategyInterface.php b/src/Symfony/Component/HttpKernel/RenderingStrategy/RenderingStrategyInterface.php
@@ -15,17 +15,25 @@
 use Symfony\Component\HttpKernel\Controller\ControllerReference;
 
 /**
+ * Interface implemented by all rendering strategies.
  *
  * @author Fabien Potencier <fabien@symfony.com>
+ *
+ * @see Symfony\Component\HttpKernel\HttpContentRenderer
  */
 interface RenderingStrategyInterface
 {
     /**
      * Renders a URI and returns the Response content.
      *
+     * When the Response is a StreamedResponse, the content is streamed immediately
+     * instead of being returned.
+     *
      * @param string|ControllerReference $uri     A URI as a string or a ControllerReference instance
      * @param Request                    $request A Request instance
      * @param array                      $options An array of options
+     *
+     * @return string|null The Response content or null when the Response is streamed
      */
     public function render($uri, Request $request = null, array $options = array());
 

diff --git a/src/Symfony/Component/HttpKernel/UriSigner.php b/src/Symfony/Component/HttpKernel/UriSigner.php
@@ -12,7 +12,7 @@
 namespace Symfony\Component\HttpKernel;
 
 /**
- * UriSigner.
+ * Signs URIs.
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */