minor #59306 [Serializer] Document SerializerInterface exceptions (VincentLanglet)

nicolas-grekas · nicolas-grekas · commit cdc1101fd84d · 2025-01-06T15:14:15.000+01:00
This PR was submitted for the 6.4 branch but it was squashed and merged into the 7.3 branch instead. Discussion ---------- [Serializer] Document `SerializerInterface` exceptions | Q | A | ------------- | --- | Branch? | 6.4 | Bug fix? | not really, just PHPDoc | New feature? | no | Deprecations? | no | Issues | Fix #...  | License | MIT This - warns the developper that calls to SerializerInterface::serialize and deserialize might throws exception - avoid PHPStan to report useless try/catch when writing ``` try { $serializer->serialize(...); } catch (NotEncodableValueException) {} // for instance ``` SerializerInterface::serialize can throws - NotEncodableValueException - all exceptions thrown by NormalizerInterface::normalize - all exceptions thrown by EncoderInterface::encode Since it might be a lot of exception and there is no real need to list them all, I simplified with ``@throws` ExceptionInterface`. Commits ------- a6aeb65 [Serializer] Document `SerializerInterface` exceptions
diff --git a/src/Symfony/Component/Serializer/SerializerInterface.php b/src/Symfony/Component/Serializer/SerializerInterface.php
@@ -11,6 +11,10 @@
 
 namespace Symfony\Component\Serializer;
 
+use Symfony\Component\Serializer\Exception\ExceptionInterface;
+use Symfony\Component\Serializer\Exception\NotNormalizableValueException;
+use Symfony\Component\Serializer\Exception\UnexpectedValueException;
+
 /**
  * @author Jordi Boggiano <j.boggiano@seld.be>
  */
@@ -20,6 +24,10 @@ interface SerializerInterface
      * Serializes data in the appropriate format.
      *
      * @param array<string, mixed> $context Options normalizers/encoders have access to
+     *
+     * @throws NotNormalizableValueException Occurs when a value cannot be normalized
+     * @throws UnexpectedValueException      Occurs when a value cannot be encoded
+     * @throws ExceptionInterface            Occurs for all the other cases of serialization-related errors
      */
     public function serialize(mixed $data, string $format, array $context = []): string;
 
@@ -35,6 +43,10 @@ public function serialize(mixed $data, string $format, array $context = []): str
      * @psalm-return (TType is class-string<TObject> ? TObject : mixed)
      *
      * @phpstan-return ($type is class-string<TObject> ? TObject : mixed)
+     *
+     * @throws NotNormalizableValueException Occurs when a value cannot be denormalized
+     * @throws UnexpectedValueException      Occurs when a value cannot be decoded
+     * @throws ExceptionInterface            Occurs for all the other cases of serialization-related errors
      */
     public function deserialize(mixed $data, string $type, string $format, array $context = []): mixed;
 }
