Merge pull request #3 from petrknap/serializer

Implemented `Serializer`

Author: petrknap

README.md

@@ -1,7 +1,7 @@
 # Library for work with binaries
 
 Library for basic work with binary data in PHP.
-See the sample below for more information, or check out [`CoderInterface`](./src/CoderInterface.php).
+See the examples below for more information, or check out [`CoderInterface`](./src/CoderInterface.php) and [`SerializerInterface`](./src/SerializerInterface.php).
 
 ```php
 use PetrKnap\Binary\Binary;
@@ -13,6 +13,19 @@ $decoded = Binary::decode($encoded)->base64()->zlib()->checksum()->getData();
 printf('Data was coded into `%s` %s.', $encoded, $decoded === $data ? 'successfully' : 'unsuccessfully');
 ```
 
+```php
+use PetrKnap\Binary\Binary;
+
+$data = [
+    'type' => 'image/png',
+    'data' => base64_decode('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAA1JREFUGFdj+L+U4T8ABu8CpCYJ1DQAAAAASUVORK5CYII='),
+];
+$serialized = Binary::serialize($data);
+$unserialized = Binary::unserialize($serialized);
+
+printf('Data was serialized into `%s` %s.', base64_encode($serialized), $unserialized === $data ? 'successfully' : 'unsuccessfully');
+```
+
 ---
 
 Run `composer require petrknap/binary` to install it.

src/Binary.php

@@ -15,4 +15,23 @@ public static function decode(string $data): Decoder
     {
         return new Decoder($data);
     }
+
+    public static function serialize(mixed $data): string
+    {
+        return self::getSerializer()->serialize(serializable: $data);
+    }
+
+    public static function unserialize(string $data): mixed
+    {
+        return self::getSerializer()->unserialize(serialized: $data);
+    }
+
+    private static function getSerializer(): Serializer
+    {
+        static $serializer;
+        return $serializer ??= new Serializer(
+            new Encoder(),
+            new Decoder(),
+        );
+    }
 }

src/Coder.php

@@ -17,10 +17,15 @@ abstract class Coder implements CoderInterface
     ];
 
     public function __construct(
-        protected readonly string $data,
+        protected readonly string $data = '',
     ) {
     }
 
+    public function withData(string $data): static
+    {
+        return static::create($this, $data);
+    }
+
     public function getData(): string
     {
         return $this->data;

src/CoderInterface.php

@@ -11,6 +11,8 @@ interface CoderInterface
 {
     public const CHECKSUM_ALGORITHM = 'crc32';
 
+    public function withData(string $data): static;
+
     public function getData(): string;
 
     /**

src/Exception/CouldNotSerializeData.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary\Exception;
+
+use PetrKnap\Binary\SerializerInterface;
+use RuntimeException;
+use Throwable;
+
+final class CouldNotSerializeData extends RuntimeException implements SerializerException
+{
+    public function __construct(
+        private readonly SerializerInterface $serializer,
+        private readonly mixed $data,
+        ?Throwable $reason = null,
+    ) {
+        parent::__construct(
+            sprintf(
+                '%s could not serialize %s',
+                $serializer::class,
+                is_object($data) ? $data::class : gettype($data),
+            ),
+            previous: $reason,
+        );
+    }
+
+    public function getSerializer(): SerializerInterface
+    {
+        return $this->serializer;
+    }
+
+    public function getData(): mixed
+    {
+        return $this->data;
+    }
+}

src/Exception/CouldNotUnserializeData.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary\Exception;
+
+use PetrKnap\Binary\SerializerInterface;
+use RuntimeException;
+use Throwable;
+
+final class CouldNotUnserializeData extends RuntimeException implements SerializerException
+{
+    public function __construct(
+        private readonly SerializerInterface $serializer,
+        private readonly string $data,
+        ?Throwable $reason = null,
+    ) {
+        parent::__construct(
+            sprintf(
+                '%s could not unserialize string(%d)',
+                $serializer::class,
+                strlen($data)
+            ),
+            previous: $reason,
+        );
+    }
+
+    public function getSerializer(): SerializerInterface
+    {
+        return $this->serializer;
+    }
+
+    public function getData(): string
+    {
+        return $this->data;
+    }
+}

src/Exception/SerializerException.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary\Exception;
+
+use PetrKnap\Binary\SerializerInterface;
+
+interface SerializerException extends BinaryException
+{
+    public function getSerializer(): SerializerInterface;
+}

src/Serializer.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+use Throwable;
+
+class Serializer implements SerializerInterface
+{
+    public function __construct(
+        protected readonly EncoderInterface $encoder,
+        protected readonly DecoderInterface $decoder,
+    ) {
+    }
+
+    public function serialize(mixed $serializable): string
+    {
+        try {
+            $serialized = $this->doSerialize($serializable);
+            return $this->encoder->withData($serialized)->zlib()->getData();
+        } catch (Throwable $reason) {
+            throw new Exception\CouldNotSerializeData($this, $serializable, $reason);
+        }
+    }
+
+    public function unserialize(string $serialized): mixed
+    {
+        try {
+            $serialized = $this->decoder->withData($serialized)->zlib()->getData();
+            return $this->doUnserialize($serialized);
+        } catch (Throwable $reason) {
+            throw new Exception\CouldNotUnserializeData($this, $serialized, $reason);
+        }
+    }
+
+    /**
+     * Alternative to {@see serialize()}
+     *
+     * @throws Throwable
+     */
+    protected function doSerialize(mixed $serializable): string
+    {
+        return serialize($serializable);
+    }
+
+    /**
+     * Alternative to {@see unserialize()}
+     *
+     * @throws Throwable
+     */
+    protected function doUnserialize(string $serialized): mixed
+    {
+        return unserialize($serialized);
+    }
+}

src/SerializerInterface.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+interface SerializerInterface
+{
+    /**
+     * {@see serialize()} the serializable
+     *
+     * @throws Exception\CouldNotSerializeData
+     */
+    public function serialize(mixed $serializable): string;
+
+    /**
+     * {@see unserialize()} the serialized
+     *
+     * @throws Exception\CouldNotUnserializeData
+     */
+    public function unserialize(string $serialized): mixed;
+}

tests/ReadmeTest.php

@@ -18,7 +18,8 @@ public static function getPathToMarkdownFile(): string
     public static function getExpectedOutputsOfPhpExamples(): iterable
     {
         return [
-            'coders' => 'Data was coded into `a8vMFCssyD2Rs5BB0Evt6tJv10J_b2Aoui0tcXT69aaPP9oIyB-fLeAHAA` successfully.',
+            'coder' => 'Data was coded into `a8vMFCssyD2Rs5BB0Evt6tJv10J_b2Aoui0tcXT69aaPP9oIyB-fLeAHAA` successfully.',
+            'serializer' => 'Data was serialized into `S7QysqoutjKxUiqpLEhVsi62srRSysxNTE/VL8hLB/GBUimJJYkgpoWxlVJngJ87L5cUFwMDA6+nh0sQkGYEYQ42ICkveqQTxCkOcndiWHdO5iVYlYtjiER48o/9Ux7aM7C9Z1qixnnFBCjB4Onq57LOKaFJyboWAA==` successfully.',
         ];
     }
 }