Exclude properties based on semver constraints

composer.json

@@ -24,12 +24,14 @@
         "phpstan/phpdoc-parser": "^0.4 || ^0.5 || ^1.0"
     },
     "suggest": {
+        "composer/semver": "Required if you like to exclude properties from serialization based on version constraints.",
         "doctrine/collections": "Required if you like to use doctrine collection types as ArrayCollection.",
         "symfony/cache": "Required if you like to use cache functionality.",
         "symfony/yaml": "Required if you'd like to use the YAML metadata format."
     },
     "require-dev": {
         "ext-pdo_sqlite": "*",
+        "composer/semver": "^1.7.4 || ^2.0 || ^3.0",
         "doctrine/coding-standard": "^8.1",
         "doctrine/orm": "~2.1",
         "doctrine/persistence": "^1.3.3|^2.0|^3.0",

doc/cookbook/exclusion_strategies.rst

@@ -57,20 +57,21 @@ expose them via an API that is consumed by a third-party:
     class VersionedObject
     {
         /**
-         * @Until("1.0.x")
+         * @VersionConstraints("<1.1")
          */
         private $name;
 
         /**
-         * @Since("1.1")
+         * @VersionConstraints(">=1.1")
          * @SerializedName("name")
          */
         private $name2;
     }
 
 .. note ::
 
-    ``@Until``, and ``@Since`` both accept a standardized PHP version number.
+    ``@VersionConstraints`` accepts `composer version constraints <https://getcomposer.org/doc/articles/versions.md#writing-version-constraints>`_.
+    ``composer/semver`` must be installed in your project.
 
 If you have annotated your objects like above, you can serializing different
 versions like this::

doc/reference/annotations.rst

@@ -76,6 +76,18 @@ property was available. If a later version is serialized, then this property is
 excluded automatically. The version must be in a format that is understood by
 PHP's ``version_compare`` function.
 
+@VersionConstraints
+~~~~~~
+This annotation can be defined on a property to specify the version constraints
+for which this property is available. This property is excluded automatically if
+a version is serialized which does not satisfy the constraints. The constraints
+must be in a format that is understood by `composer
+<https://getcomposer.org/doc/articles/versions.md#writing-version-constraints>`_.
+
+.. note ::
+
+    ``composer/semver`` must be installed in your project.
+
 @Groups
 ~~~~~~~
 This annotation can be defined on a property to specify if the property

doc/reference/xml_reference.rst

@@ -79,6 +79,7 @@ XML Reference
                       serialized-name="foo"
                       since-version="1.0"
                       until-version="1.1"
+                      version-constraints=">=1.0 <1.2"
                       xml-attribute="true"
                       access-type="public_method"
                       accessor-getter="getSomeProperty"

doc/reference/yml_reference.rst

@@ -51,6 +51,7 @@ YAML Reference
                 serialized_name: foo
                 since_version: 1.0
                 until_version: 1.1
+                version_constraints: ">=1.0 <1.2"
                 groups: [foo, bar]
                 xml_attribute: true
                 xml_value: true

src/Annotation/VersionConstraints.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace JMS\Serializer\Annotation;
+
+use Composer\Semver\Semver;
+
+/**
+ * @Annotation
+ * @Target({"PROPERTY", "METHOD", "ANNOTATION"})
+ */
+#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::TARGET_PROPERTY)]
+final class VersionConstraints extends Version
+{
+    public function __construct($values = [], ?string $version = null)
+    {
+        if (!class_exists(Semver::class)) {
+            throw new \LogicException(sprintf('composer/semver must be installed to use "%s".', self::class));
+        }
+
+        parent::__construct($values, $version);
+    }
+}

src/Exclusion/VersionExclusionStrategy.php

@@ -4,6 +4,7 @@
 
 namespace JMS\Serializer\Exclusion;
 
+use Composer\Semver\Semver;
 use JMS\Serializer\Context;
 use JMS\Serializer\Metadata\ClassMetadata;
 use JMS\Serializer\Metadata\PropertyMetadata;
@@ -27,6 +28,10 @@ public function shouldSkipClass(ClassMetadata $metadata, Context $navigatorConte
 
     public function shouldSkipProperty(PropertyMetadata $property, Context $navigatorContext): bool
     {
+        if ((null !== $constraints = $property->versionConstraints) && !Semver::satisfies($this->version, $constraints)) {
+            return true;
+        }
+
         if ((null !== $version = $property->sinceVersion) && version_compare($this->version, $version, '<')) {
             return true;
         }

src/Metadata/Driver/AnnotationDriver.php

@@ -24,6 +24,7 @@
 use JMS\Serializer\Annotation\SkipWhenEmpty;
 use JMS\Serializer\Annotation\Type;
 use JMS\Serializer\Annotation\Until;
+use JMS\Serializer\Annotation\VersionConstraints;
 use JMS\Serializer\Annotation\VirtualProperty;
 use JMS\Serializer\Annotation\XmlAttribute;
 use JMS\Serializer\Annotation\XmlAttributeMap;
@@ -182,6 +183,8 @@ public function loadMetadataForClass(\ReflectionClass $class): ?BaseClassMetadat
                         $propertyMetadata->sinceVersion = $annot->version;
                     } elseif ($annot instanceof Until) {
                         $propertyMetadata->untilVersion = $annot->version;
+                    } elseif ($annot instanceof VersionConstraints) {
+                        $propertyMetadata->versionConstraints = $annot->version;
                     } elseif ($annot instanceof SerializedName) {
                         $propertyMetadata->serializedName = $annot->name;
                     } elseif ($annot instanceof SkipWhenEmpty) {

src/Metadata/Driver/XmlDriver.php

@@ -219,6 +219,10 @@ protected function loadMetadataFromFile(\ReflectionClass $class, string $path):
                         $pMetadata->untilVersion = (string) $version;
                     }
 
+                    if (null !== $constraints = $pElem->attributes()->{'version-constraints'}) {
+                        $pMetadata->versionConstraints = (string) $constraints;
+                    }
+
                     if (null !== $serializedName = $pElem->attributes()->{'serialized-name'}) {
                         $pMetadata->serializedName = (string) $serializedName;
                     }

src/Metadata/Driver/YamlDriver.php

@@ -189,6 +189,10 @@ protected function loadMetadataFromFile(ReflectionClass $class, string $file): ?
                         $pMetadata->untilVersion = (string) $pConfig['until_version'];
                     }
 
+                    if (isset($pConfig['version_constraints'])) {
+                        $pMetadata->versionConstraints = (string) $pConfig['version_constraints'];
+                    }
+
                     if (isset($pConfig['exclude_if'])) {
                         $pMetadata->excludeIf = $this->parseExpression((string) $pConfig['exclude_if']);
                     }

src/Metadata/PropertyMetadata.php

@@ -21,6 +21,10 @@ class PropertyMetadata extends BasePropertyMetadata
      * @var string
      */
     public $untilVersion;
+    /**
+     * @var string
+     */
+    public $versionConstraints;
     /**
      * @var string[]
      */
@@ -239,6 +243,7 @@ public function serialize()
             'excludeIf' => $this->excludeIf,
             'skipWhenEmpty' => $this->skipWhenEmpty,
             'forceReflectionAccess' => $this->forceReflectionAccess,
+            'versionConstraints' => $this->versionConstraints,
         ]);
     }
 
@@ -304,6 +309,10 @@ protected function unserializeProperties(string $str): string
             $this->forceReflectionAccess = $unserialized['forceReflectionAccess'];
         }
 
+        if (isset($unserialized['versionConstraints'])) {
+            $this->versionConstraints = $unserialized['versionConstraints'];
+        }
+
         return $parentStr;
     }
 }

tests/Fixtures/ObjectWithVersionedVirtualProperties.php

@@ -8,6 +8,7 @@
 use JMS\Serializer\Annotation\SerializedName;
 use JMS\Serializer\Annotation\Since;
 use JMS\Serializer\Annotation\Until;
+use JMS\Serializer\Annotation\VersionConstraints;
 use JMS\Serializer\Annotation\VirtualProperty;
 
 /**
@@ -19,12 +20,18 @@
  *     options={@Until("8")}
  * )
  * @VirtualProperty(
+ *     "classsemver",
+ *     exp="object.getVirtualValue(61)",
+ *     options={@VersionConstraints("^6.1")}
+ * )
+ * @VirtualProperty(
  *     "classhigh",
  *     exp="object.getVirtualValue(8)",
  *     options={@Since("6")}
  * )
  */
 #[VirtualProperty(name: 'classlow', exp: 'object.getVirtualValue(1)', options: [[Until::class, ['8']]])]
+#[VirtualProperty(name: 'classsemver', exp: 'object.getVirtualValue(61)', options: [[VersionConstraints::class, ['^6.1']]])]
 #[VirtualProperty(name: 'classhigh', exp: 'object.getVirtualValue(8)', options: [[Since::class, ['6']]])]
 class ObjectWithVersionedVirtualProperties
 {
@@ -43,6 +50,21 @@ public function getVirtualLowValue()
         return 1;
     }
 
+    /**
+     * @Groups({"versions"})
+     * @VirtualProperty
+     * @SerializedName("semver")
+     * @VersionConstraints("6.1")
+     */
+    #[Groups(groups: ['versions'])]
+    #[VirtualProperty]
+    #[SerializedName(name: 'semver')]
+    #[VersionConstraints('^6.1')]
+    public function getVirtualSemverValue()
+    {
+        return 61;
+    }
+
     /**
      * @Groups({"versions"})
      * @VirtualProperty

tests/Serializer/BaseSerializationTest.php

@@ -1333,7 +1333,7 @@ public function testVirtualVersions()
 
         self::assertEquals(
             $this->getContent('virtual_properties_all'),
-            $serializer->serialize(new ObjectWithVersionedVirtualProperties(), $this->getFormat(), SerializationContext::create()->setVersion('7'))
+            $serializer->serialize(new ObjectWithVersionedVirtualProperties(), $this->getFormat(), SerializationContext::create()->setVersion('6.1'))
         );
 
         self::assertEquals(

tests/Serializer/JsonSerializationTest.php

@@ -82,7 +82,7 @@ protected function getContent($key)
             $outputs['virtual_properties'] = '{"exist_field":"value","virtual_value":"value","test":"other-name","typed_virtual_property":1}';
             $outputs['virtual_properties_low'] = '{"classlow":1,"low":1}';
             $outputs['virtual_properties_high'] = '{"classhigh":8,"high":8}';
-            $outputs['virtual_properties_all'] = '{"classlow":1,"classhigh":8,"low":1,"high":8}';
+            $outputs['virtual_properties_all'] = '{"classlow":1,"classsemver":61,"classhigh":8,"low":1,"semver":61,"high":8}';
             $outputs['nullable'] = '{"foo":"bar","baz":null,"0":null}';
             $outputs['nullable_skip'] = '{"foo":"bar"}';
             $outputs['person_secret_show'] = '{"name":"mike","gender":"f"}';

tests/Serializer/xml/virtual_properties_all.xml

@@ -1,7 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <result>
   <classlow>1</classlow>
+  <classsemver>61</classsemver>
   <classhigh>8</classhigh>
   <low>1</low>
+  <semver>61</semver>
   <high>8</high>
 </result>