From 403bb060ce45cc48df9b0ff299ba8f2aa53de21a Mon Sep 17 00:00:00 2001 From: Fabien Potencier Date: Fri, 4 Jan 2013 18:38:08 +0100 Subject: [PATCH] [HttpKernel] added missing phpdoc and tweaked existing ones --- .../Controller/ControllerReference.php | 16 +++++++++++- .../EventListener/RouterProxyListener.php | 2 +- .../HttpKernel/HttpContentRenderer.php | 18 ++++++++++++- .../DefaultRenderingStrategy.php | 12 +++++++++ .../EsiRenderingStrategy.php | 26 +++++++++++++++---- .../GeneratorAwareRenderingStrategy.php | 6 +++++ .../HIncludeRenderingStrategy.php | 14 ++++++++++ .../RenderingStrategyInterface.php | 8 ++++++ .../Component/HttpKernel/UriSigner.php | 2 +- 9 files changed, 95 insertions(+), 9 deletions(-) diff --git a/src/Symfony/Component/HttpKernel/Controller/ControllerReference.php b/src/Symfony/Component/HttpKernel/Controller/ControllerReference.php index 90ac2ba41a..905e89f5dc 100644 --- a/src/Symfony/Component/HttpKernel/Controller/ControllerReference.php +++ b/src/Symfony/Component/HttpKernel/Controller/ControllerReference.php @@ -12,9 +12,16 @@ 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 + * + * @see Symfony\Component\HttpKernel\HttpContentRenderer + * @see Symfony\Component\HttpKernel\RenderingStrategy\RenderingStrategyInterface */ class ControllerReference { @@ -22,6 +29,13 @@ class ControllerReference 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 index ff339dc020..05e8717fc0 100644 --- a/src/Symfony/Component/HttpKernel/EventListener/RouterProxyListener.php +++ b/src/Symfony/Component/HttpKernel/EventListener/RouterProxyListener.php @@ -22,7 +22,7 @@ use Symfony\Component\EventDispatcher\EventSubscriberInterface; /** * 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 diff --git a/src/Symfony/Component/HttpKernel/HttpContentRenderer.php b/src/Symfony/Component/HttpKernel/HttpContentRenderer.php index b62e0491c3..5344917ee1 100644 --- a/src/Symfony/Component/HttpKernel/HttpContentRenderer.php +++ b/src/Symfony/Component/HttpKernel/HttpContentRenderer.php @@ -19,6 +19,7 @@ use Symfony\Component\HttpKernel\RenderingStrategy\RenderingStrategyInterface; use Symfony\Component\EventDispatcher\EventSubscriberInterface; /** + * Renders a URI using different strategies. * * @author Fabien Potencier */ @@ -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 @@ class HttpContentRenderer implements EventSubscriberInterface $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 @@ class HttpContentRenderer implements EventSubscriberInterface /** * 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 @@ class HttpContentRenderer implements EventSubscriberInterface ); } + // 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 index 1b6d252365..5198c01ba9 100644 --- a/src/Symfony/Component/HttpKernel/RenderingStrategy/DefaultRenderingStrategy.php +++ b/src/Symfony/Component/HttpKernel/RenderingStrategy/DefaultRenderingStrategy.php @@ -16,6 +16,7 @@ use Symfony\Component\HttpKernel\HttpKernelInterface; use Symfony\Component\HttpKernel\Controller\ControllerReference; /** + * Implements the default rendering strategy where the Request is rendered by the current HTTP kernel. * * @author Fabien Potencier */ @@ -23,11 +24,19 @@ 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 @@ class DefaultRenderingStrategy extends GeneratorAwareRenderingStrategy 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 index be9bdb9351..cf9f572079 100644 --- a/src/Symfony/Component/HttpKernel/RenderingStrategy/EsiRenderingStrategy.php +++ b/src/Symfony/Component/HttpKernel/RenderingStrategy/EsiRenderingStrategy.php @@ -16,6 +16,7 @@ use Symfony\Component\HttpKernel\Controller\ControllerReference; use Symfony\Component\HttpKernel\HttpCache\Esi; /** + * Implements the ESI rendering strategy. * * @author Fabien Potencier */ @@ -24,6 +25,16 @@ 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; @@ -31,15 +42,17 @@ class EsiRenderingStrategy extends GeneratorAwareRenderingStrategy } /** + * {@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 @@ class EsiRenderingStrategy extends GeneratorAwareRenderingStrategy 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 index 7b5ecb5295..408d682326 100644 --- a/src/Symfony/Component/HttpKernel/RenderingStrategy/GeneratorAwareRenderingStrategy.php +++ b/src/Symfony/Component/HttpKernel/RenderingStrategy/GeneratorAwareRenderingStrategy.php @@ -17,6 +17,7 @@ use Symfony\Component\Routing\Generator\UrlGeneratorInterface; use Symfony\Component\Routing\Exception\RouteNotFoundException; /** + * Adds the possibility to generate a proxy URI for a given Controller. * * @author Fabien Potencier */ @@ -24,6 +25,11 @@ abstract class GeneratorAwareRenderingStrategy implements RenderingStrategyInter { 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 index b91a3b8800..1a67cbe45c 100644 --- a/src/Symfony/Component/HttpKernel/RenderingStrategy/HIncludeRenderingStrategy.php +++ b/src/Symfony/Component/HttpKernel/RenderingStrategy/HIncludeRenderingStrategy.php @@ -17,6 +17,7 @@ use Symfony\Component\HttpKernel\Controller\ControllerReference; use Symfony\Component\HttpKernel\UriSigner; /** + * Implements the Hinclude rendering strategy. * * @author Fabien Potencier */ @@ -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 @@ class HIncludeRenderingStrategy extends GeneratorAwareRenderingStrategy $this->signer = $signer; } + /** + * {@inheritdoc} + */ public function render($uri, Request $request = null, array $options = array()) { if ($uri instanceof ControllerReference) { @@ -95,6 +106,9 @@ class HIncludeRenderingStrategy extends GeneratorAwareRenderingStrategy 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 index e386751448..36419c3792 100644 --- a/src/Symfony/Component/HttpKernel/RenderingStrategy/RenderingStrategyInterface.php +++ b/src/Symfony/Component/HttpKernel/RenderingStrategy/RenderingStrategyInterface.php @@ -15,17 +15,25 @@ use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpKernel\Controller\ControllerReference; /** + * Interface implemented by all rendering strategies. * * @author Fabien Potencier + * + * @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 index 2ff6b9b2aa..3530c31a77 100644 --- 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 */