Merge pull request #636 from FriendsOfSymfony/version_listener

add VersionListener

Author: lsmith77

DependencyInjection/Configuration.php

@@ -203,6 +203,13 @@ private function addFormatListenerSection(ArrayNodeDefinition $rootNode)
                                 ->end()
                             ->end()
                         ->end()
+                        ->arrayNode('media_type')
+                            ->children()
+                                ->scalarNode('version_regex')
+                                    ->defaultValue('/(v|version)=(?P<version>[0-9\.]+)/')
+                                ->end()
+                            ->end()
+                        ->end()
                     ->end()
                 ->end()
             ->end();

DependencyInjection/FOSRestExtension.php

@@ -144,6 +144,12 @@ public function load(array $configs, ContainerBuilder $container)
                 $container->getDefinition($this->getAlias().'.format_negotiator')
                     ->addMethodCall('add', array($matcher, $rule));
             }
+
+            if (!empty($config['format_listener']['media_type']['version_regex'])) {
+                $container->setParameter($this->getAlias().'.format_listener.media_type.version_regex', $config['format_listener']['media_type']['version_regex']);
+            } else {
+                $container->removeDefinition('fos_rest.version_listener');
+            }
         }
 
         if (!empty($config['view']['exception_wrapper_handler'])) {

EventListener/VersionListener.php

@@ -0,0 +1,59 @@
+<?php
+
+/*
+ * This file is part of the FOSRestBundle package.
+ *
+ * (c) FriendsOfSymfony <http://friendsofsymfony.github.com/>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace FOS\RestBundle\EventListener;
+
+use FOS\RestBundle\View\ConfigurableViewHandlerInterface;
+use FOS\RestBundle\View\ViewHandlerInterface;
+use Symfony\Component\HttpKernel\Event\GetResponseEvent;
+
+class VersionListener
+{
+    /** @var ViewHandlerInterface */
+    private $viewHandler;
+
+    /** @var string */
+    private $regex;
+
+    /** @var string */
+    private $version = false;
+
+    public function getVersion()
+    {
+        return $this->version;
+    }
+
+    public function __construct(ViewHandlerInterface $viewHandler)
+    {
+        $this->viewHandler = $viewHandler;
+    }
+
+    public function setRegex($regex)
+    {
+        $this->regex = $regex;
+    }
+
+    public function onKernelRequest(GetResponseEvent $event)
+    {
+        $request = $event->getRequest();
+
+        $mediaType = $request->attributes->get('media_type');
+
+        if (1 === preg_match($this->regex, $mediaType, $matches)) {
+            $this->version = $matches['version'];
+            $request->attributes->set('version', $this->version);
+
+            if ($this->viewHandler instanceof ConfigurableViewHandlerInterface) {
+                $this->viewHandler->setExclusionStrategyVersion($this->version);
+            }
+        }
+    }
+}

Resources/config/format_listener.xml

@@ -5,9 +5,8 @@
     xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
 
     <parameters>
-
         <parameter key="fos_rest.format_listener.class">FOS\RestBundle\EventListener\FormatListener</parameter>
-
+        <parameter key="fos_rest.version_listener.class">FOS\RestBundle\EventListener\VersionListener</parameter>
     </parameters>
 
     <services>
@@ -17,5 +16,13 @@
             <argument type="service" id="fos_rest.format_negotiator" />
         </service>
 
+        <service id="fos_rest.version_listener" class="%fos_rest.version_listener.class%">
+            <argument type="service" id="fos_rest.view_handler.default" />
+            <call method="setRegex">
+                <argument type="string">%fos_rest.format_listener.media_type.version_regex%</argument>
+            </call>
+            <tag name="kernel.event_listener" event="kernel.request" method="onKernelRequest" />
+        </service>
+
     </services>
 </container>

Resources/doc/3-listener-support.md

@@ -375,6 +375,23 @@ natively or it needs to be added as documented here or using the mime type
 listener explained below:
 http://symfony.com/doc/current/cookbook/request/mime_type.html
 
+The format listener can also determine the version of the selected media type
+based on a regular expression. The regular expression can be configured as
+follows. Setting it to an empty value will disable the behavior entirely.
+
+```
+fos_rest:
+    format_listener:
+        media_type:
+            version_regex:        '/(v|version)=(?P<version>[0-9\.]+)/'
+```
+
+The matched version is set as a Request attribute with the name ``version``,
+and when using JMS serializer it is also set as an exclusion strategy
+automatically in the ``ViewHandler``. See the following documentation
+for details:
+http://jmsyst.com/libs/serializer/master/cookbook/exclusion_strategies#versioning-objects
+
 ### Mime type listener
 
 This listener allows registering additional mime types in the ``Request``

Resources/doc/configuration-reference.md

@@ -86,5 +86,7 @@ fos_rest:
 
                     # Prototype
                     name:                 []
+        media_type:
+            version_regex:        '/(v|version)=(?P<version>[0-9\.]+)/'
 ```