Merge pull request #34 from sunrise-php/release/v3.7.0

v3.7.0
sunrise-php · Jan 4, 2024 · ed4839e · ed4839e
2 parents 25077e5 + 68bbda7
commit ed4839e
Show file tree

Hide file tree

Showing 28 changed files with 386 additions and 162 deletions.
diff --git a/README.md b/README.md
@@ -37,6 +37,7 @@ composer require sunrise/hydrator
 * [Ignored property](#ignored-property)
 * [Property alias](#property-alias)
 * [Error handling](#error-handling)
+* [Localization](#localization)
 * [Doctrine annotations](#doctrine-annotations)
 
 ## How to use
@@ -519,6 +520,39 @@ try {
 }
 ```
 
+## Localization
+
+```php
+$localizedMessages = [
+    // using the error code dictionary...
+    \Sunrise\Hydrator\Dictionary\ErrorCode::INVALID_TIMESTAMP => 'Это значение не является валидной временной меткой; ожидаемый формат: {expected_format}.',
+
+    // or using the error message dictionary...
+    \Sunrise\Hydrator\Dictionary\ErrorMessage::INVALID_TIMESTAMP => 'Это значение не является валидной временной меткой; ожидаемый формат: {expected_format}.',
+];
+
+try {
+    $hydrator->hydrate(...);
+} catch (\Sunrise\Hydrator\Exception\InvalidDataException $e) {
+    foreach ($e->getExceptions() as $error) {
+        // original message...
+        $message = $error->getMessage();
+
+        // using the error code dictionary...
+        if (isset($localizedMessages[$error->getErrorCode()])) {
+            // localized message
+            $message = \strtr($localizedMessages[$error->getErrorCode()], $error->getMessagePlaceholders()), PHP_EOL;
+        }
+
+        // or using the error message dictionary...
+        if (isset($localizedMessages[$error->getMessageTemplate()])) {
+            // localized message
+            $message = \strtr($localizedMessages[$error->getMessageTemplate()], $error->getMessagePlaceholders()), PHP_EOL;
+        }
+    }
+}
+```
+
 ## Doctrine annotations
 
 To use annotations, you need to install the `doctrine/annotations` package:

diff --git a/src/Dictionary/ErrorMessage.php b/src/Dictionary/ErrorMessage.php
@@ -0,0 +1,35 @@
+<?php
+
+/**
+ * It's free open-source software released under the MIT License.
+ *
+ * @author Anatoly Nekhay <[email protected]>
+ * @copyright Copyright (c) 2021, Anatoly Nekhay
+ * @license https://github.com/sunrise-php/hydrator/blob/master/LICENSE
+ * @link https://github.com/sunrise-php/hydrator
+ */
+
+declare(strict_types=1);
+
+namespace Sunrise\Hydrator\Dictionary;
+
+/**
+ * Hydration error messages
+ *
+ * @since 3.7.0
+ */
+final class ErrorMessage
+{
+    public const MUST_BE_PROVIDED = 'This value must be provided.';
+    public const MUST_NOT_BE_EMPTY = 'This value must not be empty.';
+    public const MUST_BE_BOOLEAN = 'This value must be of type boolean.';
+    public const MUST_BE_INTEGER = 'This value must be of type integer.';
+    public const MUST_BE_NUMBER = 'This value must be of type number.';
+    public const MUST_BE_STRING = 'This value must be of type string.';
+    public const MUST_BE_ARRAY = 'This value must be of type array.';
+    public const ARRAY_OVERFLOW = 'This value is limited to {maximum_elements} elements.';
+    public const INVALID_CHOICE = 'This value is not a valid choice; expected values: {expected_values}.';
+    public const INVALID_TIMESTAMP = 'This value is not a valid timestamp; expected format: {expected_format}.';
+    public const INVALID_TIMEZONE = 'This value is not a valid timezone.';
+    public const INVALID_UID = 'This value is not a valid UID.';
+}
diff --git a/src/Exception/InvalidObjectException.php b/src/Exception/InvalidObjectException.php
@@ -32,6 +32,8 @@ class InvalidObjectException extends LogicException implements ExceptionInterfac
      * @param string $className
      *
      * @return self
+     *
+     * @since 3.2.0
      */
     final public static function uninstantiableObject(string $className): self
     {
@@ -45,6 +47,8 @@ final public static function uninstantiableObject(string $className): self
      * @param Type $type
      *
      * @return self
+     *
+     * @since 3.2.0
      */
     final public static function unsupportedType(Type $type): self
     {
@@ -69,6 +73,8 @@ final public static function unsupportedType(Type $type): self
      * @param ReflectionProperty $property
      *
      * @return self
+     *
+     * @since 3.2.0
      */
     final public static function unsupportedPropertyType(Type $type, ReflectionProperty $property): self
     {
@@ -85,6 +91,8 @@ final public static function unsupportedPropertyType(Type $type, ReflectionPrope
      * @param ReflectionParameter $parameter
      *
      * @return self
+     *
+     * @since 3.2.0
      */
     final public static function unsupportedParameterType(Type $type, ReflectionParameter $parameter): self
     {
@@ -101,6 +109,8 @@ final public static function unsupportedParameterType(Type $type, ReflectionPara
      * @param ReflectionMethod $method
      *
      * @return self
+     *
+     * @since 3.2.0
      */
     // phpcs:ignore Generic.Files.LineLength
     final public static function unsupportedMethodParameterType(Type $type, ReflectionParameter $parameter, ReflectionMethod $method): self
@@ -121,6 +131,8 @@ final public static function unsupportedMethodParameterType(Type $type, Reflecti
      * @param ReflectionFunctionAbstract $function
      *
      * @return self
+     *
+     * @since 3.2.0
      */
     // phpcs:ignore Generic.Files.LineLength
     final public static function unsupportedFunctionParameterType(Type $type, ReflectionParameter $parameter, ReflectionFunctionAbstract $function): self