docs: custom bundle / normalizers (#176)

* docs: cleanup

* docs: example of using a custom bundle / normalizers

* docs: example of using a custom bundle / normalizers

* docs: example of using a custom bundle / normalizers

* docs: example of using a custom bundle / normalizers

* docs: example of using a custom bundle / normalizers

* docs: example of using a custom bundle / normalizers

* fix: mark ArrayReference annotation as used

* fix: mark ArrayReference annotation as used

README.md

@@ -115,6 +115,17 @@ Features included:
 *(for easy integration into existing apps)*
 - CLI *(command-line interface)* tool
 
+## Custom normalizers / validators
+
+You can use your own normalizers / validators by passing your own Symfony bundle
+which registers them to the Xezilaires commands via `--bundle`, like so: 
+
+```
+vendor/bin/xezilaires validate --bundle Xezilaires\\Test\\ExampleBundle\\XezilairesExampleBundle Xezilaires\\Test\\Model\\Product src/Xezilaires/Test/resources/fixtures/products.xlsx 
+```
+
+See example bundle in [`src/Xezilaires/Test/ExampleBundle/`](./src/Xezilaires/Test/ExampleBundle/).
+
 ## What's with the name
 
 `xezilaires` is `serializex` backwards.

phpstan.neon.dist

@@ -13,6 +13,7 @@ parameters:
     excludePaths:
         - src/Bridge/*/var/*
         - src/Bridge/*/vendor/*
+        - src/Xezilaires/Test/ExampleBundle/XezilairesExampleBundle.php
         - src/Xezilaires/var/
         - src/Xezilaires/vendor/
         - var/

psalm.xml.dist

@@ -7,6 +7,7 @@
         <directory name="."/>
         <ignoreFiles allowMissingFiles="true">
             <file name=".php-cs-fixer.dist.php"/>
+            <file name="src/Xezilaires/Test/ExampleBundle/XezilairesExampleBundle.php"/>
             <directory name="src/Bridge/*/var/"/>
             <directory name="src/Bridge/*/vendor/"/>
             <directory name="src/Xezilaires/var/"/>

src/Xezilaires/Annotation/ArrayReference.php

@@ -18,10 +18,19 @@
  *
  * @Target({"PROPERTY"})
  */
+#[\Attribute(\Attribute::TARGET_PROPERTY)]
 final class ArrayReference
 {
     /**
-     * @var \Xezilaires\Annotation\Reference[]
+     * @var Reference[]
      */
     public array $references;
+
+    /**
+     * @param Reference[] $references
+     */
+    public function __construct(array $references)
+    {
+        $this->references = $references;
+    }
 }

src/Xezilaires/Test/ExampleBundle/Serializer/ProductNormalizer.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the xezilaires project.
+ *
+ * (c) sigwin.hr
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace Xezilaires\Test\ExampleBundle\Serializer;
+
+use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
+use Xezilaires\Test\Model\Product;
+
+final class ProductNormalizer implements DenormalizerInterface
+{
+    public function denormalize(mixed $data, string $type, string $format = null, array $context = []): object
+    {
+        /**
+         * @phpstan-ignore-next-line
+         *
+         * @psalm-suppress MixedArrayAccess
+         */
+        if (isset($data['all'][1])) {
+            /**
+             * @phpstan-ignore-next-line
+             *
+             * @psalm-suppress MixedArgument
+             * @psalm-suppress MixedArrayAccess
+             * @psalm-suppress MixedArrayAssignment
+             */
+            $data['all'][1] = $this->cast($data['all'][1]);
+        }
+
+        /**
+         * @phpstan-ignore-next-line
+         *
+         * @psalm-suppress MixedArgument
+         * @psalm-suppress MixedArrayAccess
+         * @psalm-suppress MixedArrayAssignment
+         */
+        $data['price'] = $this->cast($data['price']);
+
+        return (object) $data;
+    }
+
+    public function supportsDenormalization(mixed $data, string $type, string $format = null): bool
+    {
+        return $type === Product::class;
+    }
+
+    private function cast(string $price): float
+    {
+        return (float) filter_var($price, \FILTER_SANITIZE_NUMBER_FLOAT, \FILTER_FLAG_ALLOW_FRACTION);
+    }
+}

src/Xezilaires/Test/ExampleBundle/XezilairesExampleBundle.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the xezilaires project.
+ *
+ * (c) sigwin.hr
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace Xezilaires\Test\ExampleBundle;
+
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+use Symfony\Component\HttpKernel\Bundle\AbstractBundle;
+
+final class XezilairesExampleBundle extends AbstractBundle
+{
+    public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void
+    {
+        $services = $container->services();
+        $services
+            ->defaults()
+                ->autoconfigure()
+                ->autowire()
+        ;
+        $services->load(__NAMESPACE__.'\\', __DIR__);
+    }
+}

src/Xezilaires/Test/Functional/FunctionalTestCase.php

@@ -140,6 +140,7 @@ public function testCanLoadSparseFixtureWithHeaderReference(): void
     }
 
     /**
+     * @uses \Xezilaires\Annotation\ArrayReference
      * @uses \Xezilaires\Annotation\ColumnReference
      * @uses \Xezilaires\Annotation\HeaderReference
      * @uses \Xezilaires\Annotation\Options

src/Xezilaires/Test/Model/Product.php

@@ -13,37 +13,28 @@
 
 namespace Xezilaires\Test\Model;
 
-use Symfony\Component\Serializer\Annotation\Groups;
+use Symfony\Component\Serializer\Annotation as Serializer;
+use Symfony\Component\Validator\Constraints as Assert;
 use Xezilaires\Annotation as XLS;
 
-/**
- * @XLS\Options(header=1, start=2)
- */
+#[XLS\Options(start: 2, header: 1)]
 final class Product
 {
-    /**
-     * @Groups({"array"})
-     *
-     * @XLS\ArrayReference({
-     *
-     *     @XLS\ColumnReference(column="A"),
-     *
-     *     @XLS\HeaderReference(header="Price USD")
-     * })
-     */
+    #[Serializer\Groups('array')]
+    #[XLS\ArrayReference([
+        new XLS\ColumnReference(column: 'A'),
+        new XLS\HeaderReference(header: 'Price USD'),
+    ])]
     public array $all;
 
-    /**
-     * @Groups({"column", "product"})
-     *
-     * @XLS\ColumnReference(column="A")
-     */
+    #[Assert\NotBlank]
+    #[Serializer\Groups(['column', 'product'])]
+    #[XLS\ColumnReference(column: 'A')]
     public string $name;
 
-    /**
-     * @Groups({"header", "product"})
-     *
-     * @XLS\HeaderReference(header="Price USD")
-     */
+    #[Assert\NotBlank]
+    #[Assert\GreaterThanOrEqual(0)]
+    #[Serializer\Groups(['header', 'product'])]
+    #[XLS\HeaderReference(header: 'Price USD')]
     public float $price;
 }

src/Xezilaires/phpstan.neon.dist

@@ -10,6 +10,7 @@ parameters:
     paths:
         - ./
     excludePaths:
+        - Test/ExampleBundle/XezilairesExampleBundle.php
         - var/
         - vendor/
     ignoreErrors:

src/Xezilaires/psalm.xml.dist

@@ -6,6 +6,7 @@
     <projectFiles>
         <directory name="."/>
         <ignoreFiles>
+            <file name="Test/ExampleBundle/XezilairesExampleBundle.php"/>
             <directory name="var/"/>
             <directory name="vendor/"/>
         </ignoreFiles>