Deprecate @ReadOnly annotation in favor of @ReadOnlyProperty

UPGRADING.md

@@ -2,6 +2,7 @@ Unreleased
 ==========
 
 - Use symfony/cache for FileSystem cache implementation instead of doctrine/cache
+- Deprecated the `@ReadOnly` annotation due to `readonly` becoming a keyword in PHP 8.1, use the `@ReadOnlyProperty` annotation instead
 
 From 2.x to 3.0.0
 =================

doc/reference/annotations.rst

@@ -147,7 +147,7 @@ be called to retrieve, or set the value of the given property:
 .. note ::
 
     If you need only to serialize your data, you can avoid providing a setter by
-    setting the property as read-only using the ``@ReadOnly`` annotation.
+    setting the property as read-only using the ``@ReadOnlyProperty`` annotation.
 
 @AccessorOrder
 ~~~~~~~~~~~~~~
@@ -273,12 +273,13 @@ should be inlined.
 
 **Note**: AccessorOrder will be using the name of the property to determine the order.
 
-@ReadOnly
-~~~~~~~~~
+@ReadOnlyProperty
+~~~~~~~~~~~~~~~~~
 This annotation can be defined on a property to indicate that the data of the property
 is read only and cannot be set during deserialization.
 
-A property can be marked as non read only with ``@ReadOnly(false)`` annotation (useful when a class is marked as read only).
+A property can be marked as non read only with ``@ReadOnlyProperty(false)`` annotation
+(useful when a class is marked as read only).
 
 @PreSerialize
 ~~~~~~~~~~~~~
@@ -444,7 +445,7 @@ Available Types:
 
 (*) If the standalone jms/serializer is used then default format is `\DateTime::ISO8601` (which is not compatible with ISO-8601 despite the name). For jms/serializer-bundle the default format is `\DateTime::ATOM` (the real ISO-8601 format) but it can be changed in `configuration`_.
 
-(**) The key type K for array-linke formats as ``array``. ``ArrayCollection``, ``iterable``, etc., is only used for deserialization, 
+(**) The key type K for array-linke formats as ``array``. ``ArrayCollection``, ``iterable``, etc., is only used for deserialization,
 for serializaiton is treated as ``string``.
 
 Examples:

src/Annotation/ReadOnly.php

@@ -7,11 +7,9 @@
 /**
  * @Annotation
  * @Target({"CLASS","PROPERTY"})
+ *
+ * @deprecated use `@ReadOnlyProperty` instead
  */
-final class ReadOnly
+final class ReadOnly extends ReadOnlyProperty
 {
-    /**
-     * @var bool
-     */
-    public $readOnly = true;
 }

src/Annotation/ReadOnlyProperty.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace JMS\Serializer\Annotation;
+
+/**
+ * @Annotation
+ * @Target({"CLASS","PROPERTY"})
+ *
+ * @final
+ */
+/* final */ class ReadOnlyProperty
+{
+    /**
+     * @var bool
+     */
+    public $readOnly = true;
+}

src/Metadata/Driver/AnnotationDriver.php

@@ -18,7 +18,7 @@
 use JMS\Serializer\Annotation\PostDeserialize;
 use JMS\Serializer\Annotation\PostSerialize;
 use JMS\Serializer\Annotation\PreSerialize;
-use JMS\Serializer\Annotation\ReadOnly;
+use JMS\Serializer\Annotation\ReadOnlyProperty;
 use JMS\Serializer\Annotation\SerializedName;
 use JMS\Serializer\Annotation\Since;
 use JMS\Serializer\Annotation\SkipWhenEmpty;
@@ -106,7 +106,7 @@ public function loadMetadataForClass(\ReflectionClass $class): ?BaseClassMetadat
                 }
             } elseif ($annot instanceof AccessType) {
                 $classAccessType = $annot->type;
-            } elseif ($annot instanceof ReadOnly) {
+            } elseif ($annot instanceof ReadOnlyProperty) {
                 $readOnlyClass = true;
             } elseif ($annot instanceof AccessorOrder) {
                 $classMetadata->setAccessorOrder($annot->order, $annot->custom);
@@ -225,7 +225,7 @@ public function loadMetadataForClass(\ReflectionClass $class): ?BaseClassMetadat
                         $propertyMetadata->xmlElementCData = $annot->cdata;
                     } elseif ($annot instanceof AccessType) {
                         $accessType = $annot->type;
-                    } elseif ($annot instanceof ReadOnly) {
+                    } elseif ($annot instanceof ReadOnlyProperty) {
                         $propertyMetadata->readOnly = $annot->readOnly;
                     } elseif ($annot instanceof Accessor) {
                         $accessor = [$annot->getter, $annot->setter];

tests/Fixtures/AuthorReadOnly.php

@@ -5,7 +5,7 @@
 namespace JMS\Serializer\Tests\Fixtures;
 
 use JMS\Serializer\Annotation\Accessor;
-use JMS\Serializer\Annotation\ReadOnly;
+use JMS\Serializer\Annotation\ReadOnlyProperty;
 use JMS\Serializer\Annotation\SerializedName;
 use JMS\Serializer\Annotation\Type;
 use JMS\Serializer\Annotation\XmlRoot;
@@ -14,7 +14,7 @@
 class AuthorReadOnly
 {
     /**
-     * @ReadOnly
+     * @ReadOnlyProperty
      * @SerializedName("id")
      */
     private $id;

tests/Fixtures/AuthorReadOnlyPerClass.php

@@ -5,19 +5,19 @@
 namespace JMS\Serializer\Tests\Fixtures;
 
 use JMS\Serializer\Annotation\Accessor;
-use JMS\Serializer\Annotation\ReadOnly;
+use JMS\Serializer\Annotation\ReadOnlyProperty;
 use JMS\Serializer\Annotation\SerializedName;
 use JMS\Serializer\Annotation\Type;
 use JMS\Serializer\Annotation\XmlRoot;
 
 /**
  * @XmlRoot("author")
- * @ReadOnly
+ * @ReadOnlyProperty
  */
 class AuthorReadOnlyPerClass
 {
     /**
-     * @ReadOnly
+     * @ReadOnlyProperty
      * @SerializedName("id")
      */
     private $id;
@@ -26,7 +26,7 @@ class AuthorReadOnlyPerClass
      * @Type("string")
      * @SerializedName("full_name")
      * @Accessor("getName")
-     * @ReadOnly(false)
+     * @ReadOnlyProperty(false)
      */
     private $name;
 

tests/Fixtures/ExcludePublicAccessor.php

@@ -6,11 +6,11 @@
 
 use JMS\Serializer\Annotation\AccessType;
 use JMS\Serializer\Annotation\Exclude;
-use JMS\Serializer\Annotation\ReadOnly;
+use JMS\Serializer\Annotation\ReadOnlyProperty;
 
 /**
  * @AccessType("public_method")
- * @ReadOnly
+ * @ReadOnlyProperty
  */
 class ExcludePublicAccessor
 {

tests/Fixtures/GetSetObject.php

@@ -6,7 +6,7 @@
 
 use JMS\Serializer\Annotation\AccessType;
 use JMS\Serializer\Annotation\Exclude;
-use JMS\Serializer\Annotation\ReadOnly;
+use JMS\Serializer\Annotation\ReadOnlyProperty;
 use JMS\Serializer\Annotation\Type;
 
 /** @AccessType("public_method") */
@@ -19,7 +19,7 @@ class GetSetObject
     private $name = 'Foo';
 
     /**
-     * @ReadOnly
+     * @ReadOnlyProperty
      */
     private $readOnlyProperty = 42;
 

tests/Fixtures/TypedProperties/User.php

@@ -14,11 +14,11 @@ class User
     public \DateTime $created;
 
     /**
-     * @Serializer\ReadOnly()
+     * @Serializer\ReadOnlyProperty()
      */
     public ?\DateTimeInterface $updated = null;
     /**
-     * @Serializer\ReadOnly()
+     * @Serializer\ReadOnlyProperty()
      */
     public iterable $tags = [];
 }