[feature] exclusion groups

doc/cookbook/exclusion_strategies.rst

@@ -73,7 +73,9 @@ expose them via an API that is consumed by a third-party:
     ``@Until``, and ``@Since`` both accept a standardized PHP version number.
 
 If you have annotated your objects like above, you can serializing different
-versions like this::
+versions like this:
+
+.. code-block :: php
 
     use JMS\Serializer\SerializationContext;
 
@@ -109,7 +111,9 @@ You can achieve that by using the ``@Groups`` annotation on your properties.
         private $createdAt;
     }
 
-You can then tell the serializer which groups to serialize in your controller::
+You can then tell the serializer which groups to serialize in your controller:
+
+.. code-block :: php
 
     use JMS\Serializer\SerializationContext;
 
@@ -120,7 +124,38 @@ You can then tell the serializer which groups to serialize in your controller::
     $serializer->serialize(new BlogPost(), 'json', SerializationContext::create()->setGroups(array('Default', 'list')));
 
     //will output $id, $title, $nbComments and $createdAt.
+
+In some cases you might want to go the other way around and serialize everything by default but exclude a property in a specific case. You can achive that by defining a exclusion group: 
+
+.. code-block :: php
 
+    use JMS\Serializer\Annotation\Exclude;
+    /**
+    * @ExclusionPolicy("none")
+    */
+    class BlogPost
+    {
+        private $id;
+
+        private $title;
+
+        /**
+         * @Exclude({"short-list"})
+         */
+        private $content;
+    }
+
+And then tell the serializer which groups to exclude:
+
+.. code-block :: php
+
+    use JMS\Serializer\SerializationContext;
+
+    $context = SerializationContext::create()->setExclusionGroups(array('short-list'));
+    $serializer->serialize(new BlogPost(), 'json', $context);
+
+    //will output $id and $title
+
 Limiting serialization depth of some properties
 -----------------------------------------------
 You can limit the depth of what will be serialized in a property with the

src/JMS/Serializer/Annotation/Exclude.php

@@ -24,4 +24,6 @@
  */
 final class Exclude
 {
+    /** @var array<string> */
+    public $groups;
 }

src/JMS/Serializer/Context.php

@@ -21,6 +21,7 @@
 use JMS\Serializer\Exception\RuntimeException;
 use JMS\Serializer\Exclusion\DepthExclusionStrategy;
 use JMS\Serializer\Exclusion\DisjunctExclusionStrategy;
+use JMS\Serializer\Exclusion\ExclusionGroupsExclusionStrategy;
 use JMS\Serializer\Exclusion\ExclusionStrategyInterface;
 use JMS\Serializer\Exclusion\GroupsExclusionStrategy;
 use JMS\Serializer\Exclusion\VersionExclusionStrategy;
@@ -72,13 +73,13 @@ public function initialize($format, VisitorInterface $visitor, GraphNavigator $n
         if ($this->initialized) {
             throw new \LogicException('This context was already initialized, and cannot be re-used.');
         }
-
-        $this->initialized = true;
         $this->format = $format;
         $this->visitor = $visitor;
         $this->navigator = $navigator;
         $this->metadataFactory = $factory;
         $this->metadataStack = new \SplStack();
+        $this->addExclusionStrategy(new ExclusionGroupsExclusionStrategy(array()));
+        $this->initialized = true;
     }
 
     public function accept($data, array $type = null)
@@ -177,6 +178,20 @@ public function setGroups($groups)
         return $this;
     }
 
+    /**
+     * @param array $exclusionGroups
+     */
+    public function setExclusionGroups($exclusionGroups)
+    {
+        if (empty($exclusionGroups)) {
+            throw new \LogicException('The exclusion groups must not be empty.');
+        }
+
+        $this->attributes->set('exclusionGroups', (array) $exclusionGroups);
+        $this->addExclusionStrategy(new ExclusionGroupsExclusionStrategy((array) $exclusionGroups));
+        return $this;
+    }
+
     public function enableMaxDepthChecks()
     {
         $this->addExclusionStrategy(new DepthExclusionStrategy());

src/JMS/Serializer/Exclusion/ExclusionGroupsExclusionStrategy.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace JMS\Serializer\Exclusion;
+
+use JMS\Serializer\Context;
+use JMS\Serializer\Metadata\ClassMetadata;
+use JMS\Serializer\Metadata\PropertyMetadata;
+
+class ExclusionGroupsExclusionStrategy implements ExclusionStrategyInterface
+{
+    private $groups = array();
+
+    public function __construct(array $groups)
+    {
+        foreach ($groups as $group) {
+            $this->groups[$group] = true;
+        }
+    }
+
+    /**
+     * Whether the class should be skipped.
+     *
+     * @param ClassMetadata $classMetadata
+     *
+     * @param Context $context
+     * @return bool
+     */
+    public function shouldSkipClass(ClassMetadata $classMetadata, Context $context)
+    {
+        return $this->shouldSkipGroup($classMetadata->exclusionGroups);
+    }
+
+    /**
+     * Whether the property should be skipped.
+     *
+     * @param PropertyMetadata $propertyMetadata
+     *
+     * @param Context $context
+     * @return bool
+     */
+    public function shouldSkipProperty(PropertyMetadata $propertyMetadata, Context $context)
+    {
+        return $this->shouldSkipGroup($propertyMetadata->exclusionGroups);
+    }
+
+    /**
+     * @param $metadataGroups
+     * @return bool
+     */
+    private function shouldSkipGroup($metadataGroups) {
+        if (false === $metadataGroups) {
+            return false;
+        }
+        if (is_array($metadataGroups) && 0 == count($metadataGroups)) {
+            return true;
+        }
+        if (!empty($this->groups) && array_intersect(array_keys($this->groups), $metadataGroups)) {
+            return true;
+        }
+
+        return false;
+    }
+}

src/JMS/Serializer/Metadata/ClassMetadata.php

@@ -50,6 +50,7 @@ class ClassMetadata extends MergeableClassMetadata
     public $accessorOrder;
     public $customOrder;
     public $handlerCallbacks = array();
+    public $exclusionGroups = false;
 
     public $discriminatorDisabled = false;
     public $discriminatorBaseClass;
@@ -225,6 +226,7 @@ public function serialize()
             $this->accessorOrder,
             $this->customOrder,
             $this->handlerCallbacks,
+            $this->exclusionGroups,
             $this->discriminatorDisabled,
             $this->discriminatorBaseClass,
             $this->discriminatorFieldName,
@@ -246,6 +248,7 @@ public function unserialize($str)
             $this->accessorOrder,
             $this->customOrder,
             $this->handlerCallbacks,
+            $this->exclusionGroups,
             $this->discriminatorDisabled,
             $this->discriminatorBaseClass,
             $this->discriminatorFieldName,

src/JMS/Serializer/Metadata/Driver/AnnotationDriver.php

@@ -74,7 +74,6 @@ public function loadMetadataForClass(\ReflectionClass $class)
         $propertiesAnnotations = array();
 
         $exclusionPolicy = 'NONE';
-        $excludeAll = false;
         $classAccessType = PropertyMetadata::ACCESS_TYPE_PROPERTY;
         $readOnlyClass = false;
         foreach ($this->reader->getClassAnnotations($class) as $annot) {
@@ -86,7 +85,8 @@ public function loadMetadataForClass(\ReflectionClass $class)
             } elseif ($annot instanceof XmlNamespace) {
                 $classMetadata->registerNamespace($annot->uri, $annot->prefix);
             } elseif ($annot instanceof Exclude) {
-                $excludeAll = true;
+                $classMetadata->exclusionGroups = $annot->groups;
+                $this->sanitizeGroupNames($classMetadata->exclusionGroups, $classMetadata->name);
             } elseif ($annot instanceof AccessType) {
                 $classAccessType = $annot->type;
             } elseif ($annot instanceof ReadOnly) {
@@ -131,23 +131,22 @@ public function loadMetadataForClass(\ReflectionClass $class)
             }
         }
 
-        if ( ! $excludeAll) {
-            foreach ($class->getProperties() as $property) {
-                if ($property->class !== $name || (isset($property->info) && $property->info['class'] !== $name)) {
-                    continue;
-                }
-                $propertiesMetadata[] = new PropertyMetadata($name, $property->getName());
-                $propertiesAnnotations[] = $this->reader->getPropertyAnnotations($property);
+        foreach ($class->getProperties() as $property) {
+            if ($property->class !== $name || (isset($property->info) && $property->info['class'] !== $name)) {
+                continue;
             }
+            $propertiesMetadata[] = new PropertyMetadata($name, $property->getName());
+            $propertiesAnnotations[] = $this->reader->getPropertyAnnotations($property);
+        }
 
-            foreach ($propertiesMetadata as $propertyKey => $propertyMetadata) {
-                $isExclude = false;
-                $isExpose = $propertyMetadata instanceof VirtualPropertyMetadata;
-                $propertyMetadata->readOnly = $propertyMetadata->readOnly || $readOnlyClass;
-                $accessType = $classAccessType;
-                $accessor = array(null, null);
+        foreach ($propertiesMetadata as $propertyKey => $propertyMetadata) {
+            $isExpose = $propertyMetadata instanceof VirtualPropertyMetadata;
+            $propertyMetadata->readOnly = $propertyMetadata->readOnly || $readOnlyClass;
+            $accessType = $classAccessType;
+            $accessor = array(null, null);
+            $exclude = false;
 
-                $propertyAnnotations = $propertiesAnnotations[$propertyKey];
+            $propertyAnnotations = $propertiesAnnotations[$propertyKey];
 
                 foreach ($propertyAnnotations as $annot) {
                     if ($annot instanceof Since) {
@@ -158,8 +157,6 @@ public function loadMetadataForClass(\ReflectionClass $class)
                         $propertyMetadata->serializedName = $annot->name;
                     } elseif ($annot instanceof Expose) {
                         $isExpose = true;
-                    } elseif ($annot instanceof Exclude) {
-                        $isExclude = true;
                     } elseif ($annot instanceof Type) {
                         $propertyMetadata->setType($annot->name);
                     } elseif ($annot instanceof XmlElement) {
@@ -194,17 +191,19 @@ public function loadMetadataForClass(\ReflectionClass $class)
                         $propertyMetadata->readOnly = $annot->readOnly;
                     } elseif ($annot instanceof Accessor) {
                         $accessor = array($annot->getter, $annot->setter);
+                    } elseif ($annot instanceof Exclude) {
+                        if (!empty($annot->groups)) {
+                            $annotationSource = $propertyMetadata->class . '->' . $propertyMetadata->name;
+                            $this->sanitizeGroupNames($annot->groups, $annotationSource);
+                            $propertyMetadata->exclusionGroups = $annot->groups;
+                        } else {
+                            $exclude = true;
+                        }
+
                     } elseif ($annot instanceof Groups) {
                         $propertyMetadata->groups = $annot->groups;
-                        foreach ((array) $propertyMetadata->groups as $groupName) {
-                            if (false !== strpos($groupName, ',')) {
-                                throw new InvalidArgumentException(sprintf(
-                                    'Invalid group name "%s" on "%s", did you mean to create multiple groups?',
-                                    implode(', ', $propertyMetadata->groups),
-                                    $propertyMetadata->class.'->'.$propertyMetadata->name
-                                ));
-                            }
-                        }
+                        $annotationSource = $propertyMetadata->class . '->' . $propertyMetadata->name;
+                        $this->sanitizeGroupNames($propertyMetadata->groups, $annotationSource);
                     } elseif ($annot instanceof Inline) {
                         $propertyMetadata->inline = true;
                     } elseif ($annot instanceof XmlAttributeMap) {
@@ -215,14 +214,29 @@ public function loadMetadataForClass(\ReflectionClass $class)
                 }
 
 
-                if ((ExclusionPolicy::NONE === $exclusionPolicy && ! $isExclude)
-                    || (ExclusionPolicy::ALL === $exclusionPolicy && $isExpose)) {
-                    $propertyMetadata->setAccessor($accessType, $accessor[0], $accessor[1]);
-                    $classMetadata->addPropertyMetadata($propertyMetadata);
-                }
+            if ((ExclusionPolicy::NONE === $exclusionPolicy && ! $exclude)
+                || (ExclusionPolicy::ALL === $exclusionPolicy && $isExpose)) {
+                $propertyMetadata->setAccessor($accessType, $accessor[0], $accessor[1]);
+                $classMetadata->addPropertyMetadata($propertyMetadata);
             }
         }
 
         return $classMetadata;
     }
+
+    /**
+     * @param array $groups
+     * @param string $annotationSource
+     */
+    private function sanitizeGroupNames($groups, $annotationSource)
+    {
+        foreach ((array)$groups as $groupName) {
+            if (false !== strpos($groupName, ',')) {
+                throw new InvalidArgumentException(sprintf(
+                    'Invalid group name "%s" on "%s", did you mean to create multiple groups?',
+                    implode(', ', $groups), $annotationSource
+                ));
+            }
+        }
+    }
 }

src/JMS/Serializer/Metadata/PropertyMetadata.php

@@ -30,6 +30,7 @@ class PropertyMetadata extends BasePropertyMetadata
     public $sinceVersion;
     public $untilVersion;
     public $groups;
+    public $exclusionGroups = false;
     public $serializedName;
     public $type;
     public $xmlCollection = false;
@@ -136,6 +137,7 @@ public function serialize()
             parent::serialize(),
             'xmlEntryNamespace' => $this->xmlEntryNamespace,
             'xmlCollectionSkipWhenEmpty' => $this->xmlCollectionSkipWhenEmpty,
+            'exclusionGroups' => $this->exclusionGroups,
         ));
     }
 
@@ -172,7 +174,9 @@ public function unserialize($str)
         if (isset($unserialized['xmlCollectionSkipWhenEmpty'])){
             $this->xmlCollectionSkipWhenEmpty = $unserialized['xmlCollectionSkipWhenEmpty'];
         }
-
+        if (isset($unserialized['exclusionGroups'])){
+            $this->exclusionGroups = $unserialized['exclusionGroups'];
+        }
 
         parent::unserialize($parentStr);
     }

tests/JMS/Serializer/Tests/Fixtures/ExclusionGroupsObject.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace JMS\Serializer\Tests\Fixtures;
+
+use JMS\Serializer\Annotation\Exclude;
+use JMS\Serializer\Annotation\Type;
+
+/**
+ * @Exclude({"noClass"})
+ */
+class ExclusionGroupsObject
+{
+    /**
+     * @Type("string")
+     * @Exclude({"testExclusionGroup1", "testExclusionGroup2"})
+     */
+    public $foo = 'foo';
+
+    /**
+     * @Type("string")
+     * @Exclude({"testExclusionGroup1"})
+     */
+    public $foo2 = 'foo2';
+
+    /**
+     * @Type("string")
+     */
+    public $bar = 'bar';
+
+    /**
+     * @Type("string")
+     * @Exclude()
+     */
+    public $neverShown = 'nevershown';
+}