From 8a577ecad8719170ed02c6d5fb185daa42745c9c Mon Sep 17 00:00:00 2001 From: Michael Babker Date: Sat, 31 Jul 2021 12:53:36 -0500 Subject: [PATCH] Deprecate ReadOnly annotation in favor of ReadOnlyProperty --- UPGRADING.md | 1 + doc/reference/annotations.rst | 11 ++++++----- src/Annotation/ReadOnly.php | 8 +++----- src/Annotation/ReadOnlyProperty.php | 19 +++++++++++++++++++ src/Metadata/Driver/AnnotationDriver.php | 6 +++--- tests/Fixtures/AuthorReadOnly.php | 4 ++-- tests/Fixtures/AuthorReadOnlyPerClass.php | 8 ++++---- tests/Fixtures/ExcludePublicAccessor.php | 4 ++-- tests/Fixtures/GetSetObject.php | 4 ++-- tests/Fixtures/TypedProperties/User.php | 4 ++-- 10 files changed, 44 insertions(+), 25 deletions(-) create mode 100644 src/Annotation/ReadOnlyProperty.php diff --git a/UPGRADING.md b/UPGRADING.md index 990ceeebd..3fe0f5bac 100644 --- a/UPGRADING.md +++ b/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 ================= diff --git a/doc/reference/annotations.rst b/doc/reference/annotations.rst index 25e8419f8..02099fa41 100644 --- a/doc/reference/annotations.rst +++ b/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: diff --git a/src/Annotation/ReadOnly.php b/src/Annotation/ReadOnly.php index 9e0336b86..5a24a9457 100644 --- a/src/Annotation/ReadOnly.php +++ b/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; } diff --git a/src/Annotation/ReadOnlyProperty.php b/src/Annotation/ReadOnlyProperty.php new file mode 100644 index 000000000..fc3a4bf08 --- /dev/null +++ b/src/Annotation/ReadOnlyProperty.php @@ -0,0 +1,19 @@ +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]; diff --git a/tests/Fixtures/AuthorReadOnly.php b/tests/Fixtures/AuthorReadOnly.php index 92dd38db7..066fbc153 100644 --- a/tests/Fixtures/AuthorReadOnly.php +++ b/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; diff --git a/tests/Fixtures/AuthorReadOnlyPerClass.php b/tests/Fixtures/AuthorReadOnlyPerClass.php index 9636b5b0b..9b97b8921 100644 --- a/tests/Fixtures/AuthorReadOnlyPerClass.php +++ b/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; diff --git a/tests/Fixtures/ExcludePublicAccessor.php b/tests/Fixtures/ExcludePublicAccessor.php index 9879b9c70..29dfa1b85 100644 --- a/tests/Fixtures/ExcludePublicAccessor.php +++ b/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 { diff --git a/tests/Fixtures/GetSetObject.php b/tests/Fixtures/GetSetObject.php index 26b01e359..eb656bc7d 100644 --- a/tests/Fixtures/GetSetObject.php +++ b/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; diff --git a/tests/Fixtures/TypedProperties/User.php b/tests/Fixtures/TypedProperties/User.php index 922ab54c4..ed0924e25 100644 --- a/tests/Fixtures/TypedProperties/User.php +++ b/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 = []; }