[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /*
   4   * This file is part of the Symfony package.
   5   *
   6   * (c) Fabien Potencier <fabien@symfony.com>
   7   *
   8   * For the full copyright and license information, please view the LICENSE
   9   * file that was distributed with this source code.
  10   */
  11  
  12  namespace Symfony\Component\HttpKernel\Fragment;
  13  
  14  use Symfony\Component\HttpFoundation\Request;
  15  use Symfony\Component\HttpFoundation\RequestStack;
  16  use Symfony\Component\HttpFoundation\Response;
  17  use Symfony\Component\HttpFoundation\StreamedResponse;
  18  use Symfony\Component\HttpKernel\Controller\ControllerReference;
  19  
  20  /**
  21   * Renders a URI that represents a resource fragment.
  22   *
  23   * This class handles the rendering of resource fragments that are included into
  24   * a main resource. The handling of the rendering is managed by specialized renderers.
  25   *
  26   * This listener works in 2 modes:
  27   *
  28   *  * 2.3 compatibility mode where you must call setRequest whenever the Request changes.
  29   *  * 2.4+ mode where you must pass a RequestStack instance in the constructor.
  30   *
  31   * @author Fabien Potencier <fabien@symfony.com>
  32   *
  33   * @see FragmentRendererInterface
  34   */
  35  class FragmentHandler
  36  {
  37      private $debug;
  38      private $renderers = array();
  39      private $request;
  40      private $requestStack;
  41  
  42      /**
  43       * RequestStack will become required in 3.0.
  44       *
  45       * @param RequestStack                $requestStack The Request stack that controls the lifecycle of requests
  46       * @param FragmentRendererInterface[] $renderers    An array of FragmentRendererInterface instances
  47       * @param bool                        $debug        Whether the debug mode is enabled or not
  48       */
  49      public function __construct($requestStack = null, $renderers = array(), $debug = false)
  50      {
  51          if (\is_array($requestStack)) {
  52              $tmp = $debug;
  53              $debug = \func_num_args() < 2 ? false : $renderers;
  54              $renderers = $requestStack;
  55              $requestStack = \func_num_args() < 3 ? null : $tmp;
  56  
  57              @trigger_error('The '.__METHOD__.' method now requires a RequestStack to be given as first argument as '.__CLASS__.'::setRequest method will not be supported anymore in 3.0.', E_USER_DEPRECATED);
  58          } elseif (!$requestStack instanceof RequestStack) {
  59              @trigger_error('The '.__METHOD__.' method now requires a RequestStack instance as '.__CLASS__.'::setRequest method will not be supported anymore in 3.0.', E_USER_DEPRECATED);
  60          }
  61  
  62          if (null !== $requestStack && !$requestStack instanceof RequestStack) {
  63              throw new \InvalidArgumentException('RequestStack instance expected.');
  64          }
  65          if (!\is_array($renderers)) {
  66              throw new \InvalidArgumentException('Renderers must be an array.');
  67          }
  68  
  69          $this->requestStack = $requestStack;
  70          foreach ($renderers as $renderer) {
  71              $this->addRenderer($renderer);
  72          }
  73          $this->debug = $debug;
  74      }
  75  
  76      /**
  77       * Adds a renderer.
  78       */
  79      public function addRenderer(FragmentRendererInterface $renderer)
  80      {
  81          $this->renderers[$renderer->getName()] = $renderer;
  82      }
  83  
  84      /**
  85       * Sets the current Request.
  86       *
  87       * This method was used to synchronize the Request, but as the HttpKernel
  88       * is doing that automatically now, you should never call it directly.
  89       * It is kept public for BC with the 2.3 version.
  90       *
  91       * @param Request|null $request A Request instance
  92       *
  93       * @deprecated since version 2.4, to be removed in 3.0.
  94       */
  95      public function setRequest(Request $request = null)
  96      {
  97          @trigger_error('The '.__METHOD__.' method is deprecated since Symfony 2.4 and will be removed in 3.0.', E_USER_DEPRECATED);
  98  
  99          $this->request = $request;
 100      }
 101  
 102      /**
 103       * Renders a URI and returns the Response content.
 104       *
 105       * Available options:
 106       *
 107       *  * ignore_errors: true to return an empty string in case of an error
 108       *
 109       * @param string|ControllerReference $uri      A URI as a string or a ControllerReference instance
 110       * @param string                     $renderer The renderer name
 111       * @param array                      $options  An array of options
 112       *
 113       * @return string|null The Response content or null when the Response is streamed
 114       *
 115       * @throws \InvalidArgumentException when the renderer does not exist
 116       * @throws \LogicException           when no master request is being handled
 117       */
 118      public function render($uri, $renderer = 'inline', array $options = array())
 119      {
 120          if (!isset($options['ignore_errors'])) {
 121              $options['ignore_errors'] = !$this->debug;
 122          }
 123  
 124          if (!isset($this->renderers[$renderer])) {
 125              throw new \InvalidArgumentException(sprintf('The "%s" renderer does not exist.', $renderer));
 126          }
 127  
 128          if (!$request = $this->getRequest()) {
 129              throw new \LogicException('Rendering a fragment can only be done when handling a Request.');
 130          }
 131  
 132          return $this->deliver($this->renderers[$renderer]->render($uri, $request, $options));
 133      }
 134  
 135      /**
 136       * Delivers the Response as a string.
 137       *
 138       * When the Response is a StreamedResponse, the content is streamed immediately
 139       * instead of being returned.
 140       *
 141       * @return string|null The Response content or null when the Response is streamed
 142       *
 143       * @throws \RuntimeException when the Response is not successful
 144       */
 145      protected function deliver(Response $response)
 146      {
 147          if (!$response->isSuccessful()) {
 148              throw new \RuntimeException(sprintf('Error when rendering "%s" (Status code is %s).', $this->getRequest()->getUri(), $response->getStatusCode()));
 149          }
 150  
 151          if (!$response instanceof StreamedResponse) {
 152              return $response->getContent();
 153          }
 154  
 155          $response->sendContent();
 156      }
 157  
 158      private function getRequest()
 159      {
 160          return $this->requestStack ? $this->requestStack->getCurrentRequest() : $this->request;
 161      }
 162  }