feat: implemented helpers for one-way object to binary string conversion

Author: petrknap

src/BinariableInterface.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+use Stringable;
+
+interface BinariableInterface extends Stringable
+{
+    /**
+     * @return string binary representation of this instance
+     *
+     * @throws Exception\CouldNotConvertToBinary
+     */
+    public function toBinary(): string;
+}

src/BinariableTrait.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+use PetrKnap\Shorts\Exception\NotImplemented;
+
+trait BinariableTrait
+{
+    /**
+     * Unfortunately PHP uses string for binary data, so the magic clashes.
+     */
+    public function __toString(): string
+    {
+        if (!($this instanceof BinariableInterface)) {
+            NotImplemented::throw(BinariableInterface::class);
+        }
+
+        $binary = $this->toBinary();
+        trigger_error(
+            'Returned binary string',
+            error_level: E_USER_NOTICE,
+        );
+        return $binary;
+    }
+}

src/Exception/BinariableException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary\Exception;
+
+interface BinariableException extends BinaryException
+{
+}

src/Exception/CouldNotConvertToBinary.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary\Exception;
+
+use PetrKnap\Shorts\Exception\CouldNotProcessData;
+
+/**
+ * @extends CouldNotProcessData<object>
+ */
+final class CouldNotConvertToBinary extends CouldNotProcessData implements BinariableException
+{
+}

tests/BinariableTest.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+use PHPUnit\Framework\TestCase;
+
+final class BinariableTest extends TestCase
+{
+    public const DATA = b'data';
+
+    public function testExplicitConversionWorks(): void
+    {
+        self::assertSame(
+            self::DATA,
+            self::getBinariable()->toBinary(),
+        );
+    }
+
+    public function testNativeConversionWorks(): void
+    {
+        self::assertSame(
+            self::DATA,
+            (string) self::getBinariable(),
+        );
+    }
+
+    public function testNativeComparisonWorks(): void
+    {
+        self::assertTrue(self::DATA == self::getBinariable());
+    }
+
+    public function testUnionTypingWorks(): void
+    {
+        $function = static fn (BinariableInterface|string $parameter): string => (string) $parameter;
+
+        self::assertSame(
+            self::DATA,
+            $function(self::getBinariable()),
+        );
+    }
+
+    private function getBinariable(): BinariableInterface
+    {
+        return new class () implements BinariableInterface {
+            use BinariableTrait;
+
+            public function toBinary(): string
+            {
+                return BinariableTest::DATA;
+            }
+        };
+    }
+}