8000 [HttpKernel] added missing phpdoc and tweaked existing ones · symfony/symfony@403bb06 · GitHub
[go: up one dir, main page]
Skip to content

Commit 403bb06

Browse files
fabpotfabpot
committed
[HttpKernel] added missing phpdoc and tweaked existing ones
1 parent 892f00f commit 403bb06

9 files changed

+95
-9
lines changed

‎src/Symfony/Component/HttpKernel/Controller/ControllerReference.php

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,30 @@
1212
namespace Symfony\Component\HttpKernel\Controller;
1313

1414
/**
15-
* ControllerReference.
15+
* Acts as a marker and a data holder for a Controller.
16+
*
17+
* Some methods in Symfony accept both a URI (as a string) or a controller as
18+
* an argument. In the latter case, instead of passing an array representing
19+
* the controller, you can use an instance of this class.
1620
*
1721
* @author Fabien Potencier <fabien@symfony.com>
22+
*
23+
* @see Symfony\Component\HttpKernel\HttpContentRenderer
24+
* @see Symfony\Component\HttpKernel\RenderingStrategy\RenderingStrategyInterface
1825
*/
1926
class ControllerReference
2027
{
2128
public $controller;
2229
public $attributes = array();
2330
public $query = array();
2431

32+
/**
33+
* Constructor.
34+
*
35+
* @param string $controller The controller name
36+
* @param array $attributes An array of parameters to add to the Request attributes
37+
* @param array $query An array of parameters to add to the Request query string
38+
*/
2539
public function __construct($controller, array $attributes = array(), array $query = array())
2640
{
2741
$this->controller = $controller;

‎src/Symfony/Component/HttpKernel/EventListener/RouterProxyListener.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
/**
2323
* Proxies URIs when the current route name is "_proxy".
2424
*
25-
* If the request does not come from a trusted, it throws an
25+
* If the request does not come from a trusted IP, it throws an
2626
* AccessDeniedHttpException exception.
2727
*
2828
* @author Fabien Potencier <fabien@symfony.com>

‎src/Symfony/Component/HttpKernel/HttpContentRenderer.php

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
2020

2121
/**
22+
* Renders a URI using different strategies.
2223
*
2324
* @author Fabien Potencier <fabien@symfony.com>
2425
*/
@@ -28,6 +29,12 @@ class HttpContentRenderer implements EventSubscriberInterface
2829
private $strategies;
2930
private $requests;
3031

32+
/**
33+
* Constructor.
34+
*
35+
* @param RenderingStrategyInterface[] $strategies An array of RenderingStrategyInterface instances
36+
* @param Boolean $debug Whether the debug mode is enabled or not
37+
*/
3138
public function __construct(array $strategies = array(), $debug = false)
3239
{
3340
$this->strategies = array();
@@ -38,6 +45,11 @@ public function __construct(array $strategies = array(), $debug = false)
3845
$this->requests = array();
3946
}
4047

48+
/**
49+
* Adds a rendering strategy.
50+
*
51+
* @param RenderingStrategyInterface $strategy A RenderingStrategyInterface instance
52+
*/
4153
public function addStrategy(RenderingStrategyInterface $strategy)
4254
{
4355
$this->strategies[$strategy->getName()] = $strategy;
@@ -66,13 +78,16 @@ public function onKernelResponse(FilterResponseEvent $event)
6678
/**
6779
* Renders a URI and returns the Response content.
6880
*
81+
* When the Response is a StreamedResponse, the content is streamed immediately
82+
* instead of being returned.
83+
*
6984
* * ignore_errors: true to return an empty string in case of an error
7085
* * strategy: the strategy to use for rendering
7186
*
7287
* @param string|ControllerReference $uri A URI as a string or a ControllerReference instance
7388
* @param array $options An array of options
7489
*
75-
* @return string The Response content
90+
* @return string|null The Response content or null when the Response is streamed
7691
*/
7792
public function render($uri, array $options = array())
7893
{
@@ -99,6 +114,7 @@ public static function getSubscribedEvents()
99114
);
100115
}
101116

117+
// to be removed in 2.3
102118
private function fixOptions($options)
103119
{
104120
// support for the standalone option is @deprecated in 2.2 and replaced with the strategy option

‎src/Symfony/Component/HttpKernel/RenderingStrategy/DefaultRenderingStrategy.php

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,18 +16,27 @@
1616
use Symfony\Component\HttpKernel\Controller\ControllerReference;
1717

1818
/**
19+
* Implements the default rendering strategy where the Request is rendered by the current HTTP kernel.
1920
*
2021
* @author Fabien Potencier <fabien@symfony.com>
2122
*/
2223
class DefaultRenderingStrategy extends GeneratorAwareRenderingStrategy
2324
{
2425
private $kernel;
2526

27+
/**
28+
* Constructor.
29+
*
30+
* @param HttpKernelInterface $kernel A HttpKernelInterface instance
31+
*/
2632
public function __construct(HttpKernelInterface $kernel)
2733
{
2834
$this->kernel = $kernel;
2935
}
3036

37+
/**
38+
* {@inheritdoc}
39+
*/
3140
public function render($uri, Request $request = null, array $options = array())
3241
{
3342
if ($uri instanceof ControllerReference) {
@@ -94,6 +103,9 @@ protected function createSubRequest($uri, Request $request = null)
94103
return $subRequest;
95104
}
96105

106+
/**
107+
* {@inheritdoc}
108+
*/
97109
public function getName()
98110
{
99111
return 'default';

‎src/Symfony/Component/HttpKernel/RenderingStrategy/EsiRenderingStrategy.php

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
use Symfony\Component\HttpKernel\HttpCache\Esi;
1717

1818
/**
19+
* Implements the ESI rendering strategy.
1920
*
2021
* @author Fabien Potencier <fabien@symfony.com>
2122
*/
@@ -24,22 +25,34 @@ class EsiRenderingStrategy extends GeneratorAwareRenderingStrategy
2425
private $esi;
2526
private $defaultStrategy;
2627

28+
/**
29+
* Constructor.
30+
*
31+
* The "fallback" strategy when ESI is not available should always be an
32+
* instance of DefaultRenderingStrategy (or a class you are using for the
33+
* default strategy).
34+
*
35+
* @param Esi $esi An Esi instance
36+
* @param RenderingStrategyInterface $defaultStrategy The default strategy to use when ESI is not supported
37+
*/
2738
public function __construct(Esi $esi, RenderingStrategyInterface $defaultStrategy)
2839
{
2940
$this->esi = $esi;
3041
$this->defaultStrategy = $defaultStrategy;
3142
}
3243

3344
/**
45+
* {@inheritdoc}
3446
*
35-
* Note that this method generates an esi:include tag only when both the standalone
36-
* option is set to true and the request has ESI capability (@see Symfony\Component\HttpKernel\HttpCache\ESI).
47+
* Note that if the current Request has no ESI capability, this method
48+
* falls back to use the default rendering strategy.
3749
*
38-
* Available options:
50+
* Additional available options:
3951
*
40-
* * ignore_errors: true to return an empty string in case of an error
41-
* * alt: an alternative URI to execute in case of an error
52+
* * alt: an alternative URI to render in case of an error
4253
* * comment: a comment to add when returning an esi:include tag
54+
*
55+
* @see Symfony\Component\HttpKernel\HttpCache\ESI
4356
*/
4457
public function render($uri, Request $request = null, array $options = array())
4558
{
@@ -59,6 +72,9 @@ public function render($uri, Request $request = null, array $options = array())
5972
return $this->esi->renderIncludeTag($uri, $alt, $options['ignore_errors'], isset($options['comment']) ? $options['comment'] : '');
6073
}
6174

75+
/**
76+
* {@inheritdoc}
77+
*/
6278
public function getName()
6379
{
6480
return 'esi';

‎src/Symfony/Component/HttpKernel/RenderingStrategy/GeneratorAwareRenderingStrategy.php

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,19 @@
1717
use Symfony\Component\Routing\Exception\RouteNotFoundException;
1818

1919
/**
20+
* Adds the possibility to generate a proxy URI for a given Controller.
2021
*
2122
* @author Fabien Potencier <fabien@symfony.com>
2223
*/
2324
abstract class GeneratorAwareRenderingStrategy implements RenderingStrategyInterface
2425
{
2526
protected $generator;
2627

28+
/**
29+
* Sets a URL generator to use for proxy URIs generation.
30+
*
31+
* @param UrlGeneratorInterface $generator An UrlGeneratorInterface instance
32+
*/
2733
public function setUrlGenerator(UrlGeneratorInterface $generator)
2834
{
2935
$this->generator = $generator;

‎src/Symfony/Component/HttpKernel/RenderingStrategy/HIncludeRenderingStrategy.php

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
use Symfony\Component\HttpKernel\UriSigner;
1818

1919
/**
20+
* Implements the Hinclude rendering strategy.
2021
*
2122
* @author Fabien Potencier <fabien@symfony.com>
2223
*/
@@ -26,6 +27,13 @@ class HIncludeRenderingStrategy extends GeneratorAwareRenderingStrategy
2627
private $globalDefaultTemplate;
2728
private $signer;
2829

30+
/**
31+
* Constructor.
32+
*
33+
* @param EngineInterface|\Twig_Environment $templating An EngineInterface or a \Twig_Environment instance
34+
* @param UriSigner $signer A UriSigner instance
35+
* @param string $globalDefaultTemplate The content of the global default template
36+
*/
2937
public function __construct($templating, UriSigner $signer = null, $globalDefaultTemplate = null)
3038
{
3139
if (!$templating instanceof EngineInterface && !$templating instanceof \Twig_Environment) {
@@ -37,6 +45,9 @@ public function __construct($templating, UriSigner $signer = null, $globalDefaul
3745
$this->signer = $signer;
3846
}
3947

48+
/**
49+
* {@inheritdoc}
50+
*/
4051
public function render($uri, Request $request = null, array $options = array())
4152
{
4253
if ($uri instanceof ControllerReference) {
@@ -95,6 +106,9 @@ private function templateExists($template)
95106
return false;
96107
}
97108

109+
/**
110+
* {@inheritdoc}
111+
*/
98112
public function getName()
99113
{
100114
return 'hinclude';

‎src/Symfony/Component/HttpKernel/RenderingStrategy/RenderingStrategyInterface.php

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,17 +15,25 @@
1515
use Symfony\Component\HttpKernel\Controller\ControllerReference;
1616

1717
/**
18+
* Interface implemented by all rendering strategies.
1819
*
1920
* @author Fabien Potencier <fabien@symfony.com>
21+
*
22+
* @see Symfony\Component\HttpKernel\HttpContentRenderer
2023
*/
2124
interface RenderingStrategyInterface
2225
{
2326
/**
2427
* Renders a URI and returns the Response content.
2528
*
29+
* When the Response is a StreamedResponse, the content is streamed immediately
30+
* instead of being returned.
31+
*
2632
* @param string|ControllerReference $uri A URI as a string or a ControllerReference instance
2733
* @param Request $request A Request instance
2834
* @param array $options An array of options
35+
*
36+
* @return string|null The Response content or null when the Response is streamed
2937
*/
3038
public function render($uri, Request $request = null, array $options = array());
3139

‎src/Symfony/Component/HttpKernel/UriSigner.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
namespace Symfony\Component\HttpKernel;
1313

1414
/**
15-
* UriSigner.
15+
* Signs URIs.
1616
*
1717
* @author Fabien Potencier <fabien@symfony.com>
1818
*/

0 commit comments

Comments
 (0)
0