Merge remote-tracking branch 'origin/main' into v4.x

Author: petrknap

Dockerfile

@@ -12,6 +12,15 @@ RUN apt-get update \
 COPY --from=composer:2 /usr/bin/composer /usr/local/bin/composer
 # endregion
 
+# region included igbinary
+# hadolint ignore=DL3008
+RUN pecl install -o -f \
+      igbinary \
+ && docker-php-ext-enable \
+      igbinary \
+;
+# endregion
+
 # region included composer-library
 WORKDIR /app
 COPY . .

composer.json

@@ -13,6 +13,9 @@
     "allow-plugins": false,
     "sort-packages": true
   },
+  "conflict": {
+    "petrknap/xz-utils": "<1|>=2"
+  },
   "description": "Library for work with binary data and objects",
   "funding": [
     {
@@ -22,6 +25,7 @@
   ],
   "homepage": "https://github.com/petrknap/php-binary",
   "keywords": [
+    "ascii",
     "base64",
     "binary",
     "checksum",
@@ -33,24 +37,28 @@
     "hexadecimal",
     "igbinary",
     "serializer",
-    "zlib"
+    "zlib",
+    "xz"
   ],
   "license": "LGPL-3.0-or-later",
   "name": "petrknap/binary",
   "require": {
     "php": ">=8.1",
-    "petrknap/shorts": "^2.0|^3.0"
+    "petrknap/optional": "^3.1",
+    "petrknap/shorts": "^3.0"
   },
   "require-dev": {
+    "ext-igbinary": "*",
     "ext-mbstring": "*",
     "ext-zlib": "*",
     "nunomaduro/phpinsights": "^2.11",
+    "petrknap/xz-utils": "*",
     "phpstan/phpstan": "^1.12",
     "phpunit/phpunit": "^10.5",
     "squizlabs/php_codesniffer": "^3.7"
   },
   "scripts": {
-    "test": "phpunit --colors=always --testdox tests",
+    "test": "@test-implementation",
     "ci-script": [
       "@check-implementation",
       "@check-requirements",
@@ -67,12 +75,13 @@
       "composer outdated \"petrknap/*\" --major-only --strict --ansi --no-interaction"
     ],
     "test-implementation": [
-      "@test"
+      "phpunit --colors=always --testdox tests"
     ]
   },
   "suggest": {
     "ext-igbinary": "Required to serialize data via igbinary",
     "ext-mbstring": "Required to bite bytes",
-    "ext-zlib": "Required to compress data"
+    "ext-zlib": "Required to compress data",
+    "petrknap/xz-utils": "Required to compress data"
   }
 }

src/Binary.php

@@ -6,12 +6,12 @@
 
 final class Binary
 {
-    public static function encode(string $data): EncoderInterface
+    public static function encode(string $data): Encoder
     {
         return new Encoder($data);
     }
 
-    public static function decode(string $data): DecoderInterface
+    public static function decode(string $data): Decoder
     {
         return new Decoder($data);
     }

src/Byter.php

@@ -7,7 +7,7 @@
 use PetrKnap\Shorts\HasRequirements;
 use RuntimeException;
 
-class Byter
+final class Byter
 {
     use HasRequirements;
 
@@ -28,15 +28,15 @@ functions: [
      *
      * @return array<string> bites of specified sizes; and remains, if any
      *
-     * @throws Exception\CouldNotBiteData
+     * @throws Exception\ByterCouldNotBiteData
      */
     public function bite(string $data, int $size1, int ...$sizeN): array
     {
         $remains = $data;
         $bites = [];
         foreach ([$size1, ...$sizeN] as $size) {
             if (abs($size) > $this->size($remains)) {
-                throw new Exception\CouldNotBiteData(__METHOD__, $data, new RuntimeException(
+                throw new Exception\ByterCouldNotBiteData(__METHOD__, $data, new RuntimeException(
                     'Remains are smaller than bite',
                 ));
             }

src/Coder.php

@@ -4,38 +4,60 @@
 
 namespace PetrKnap\Binary;
 
-use PetrKnap\Shorts\Exception;
 use Stringable;
 
 /**
- * @internal please use subclass
- *
- * @phpstan-consistent-constructor override {@see self::create()} if not
- *
- * @implements CoderInterface<Exception\CouldNotProcessData>
+ * @internal shared logic
  */
-abstract class Coder implements CoderInterface, Stringable
+abstract class Coder implements Stringable
 {
     /**
      * @param string $data may contain binary data
      */
-    public function __construct(
+    final public function __construct(
         public readonly string $data = '',
     ) {
     }
 
-    public function withData(string $data): static
+    final public function withData(string $data): static
     {
-        return static::create($this, $data);
+        return new static($data);
     }
 
     /**
-     * @deprecated use readonly property {@see self::$data}
+     * @see Coder\Base64
+     *
+     * @throws Coder\Exception\CoderException
      */
-    final public function getData(): string
-    {
-        return $this->data;
-    }
+    abstract public function base64(): static;
+
+    /**
+     * @see Coder\Checksum
+     *
+     * @throws Coder\Exception\CoderException
+     */
+    abstract public function checksum(string|null $algorithm = null): static;
+
+    /**
+     * @see Coder\Hex
+     *
+     * @throws Coder\Exception\CoderException
+     */
+    abstract public function hex(): static;
+
+    /**
+     * @see Coder\Xz
+     *
+     * @throws Coder\Exception\CoderException
+     */
+    abstract public function xz(): static;
+
+    /**
+     * @see Coder\zlib
+     *
+     * @throws Coder\Exception\CoderException
+     */
+    abstract public function zlib(): static;
 
     /**
      * @note this is just a helper, this class is not supposed to implement {@see BinariableInterface}
@@ -44,9 +66,4 @@ public function __toString(): string
     {
         return $this->data;
     }
-
-    protected static function create(self $coder, string $data): static
-    {
-        return new static($data);
-    }
 }

src/Coder/Base64.php

@@ -4,23 +4,24 @@
 
 namespace PetrKnap\Binary\Coder;
 
+use PetrKnap\Optional\OptionalString;
+
 /**
  * @see base64_encode()
  * @see base64_decode()
  */
 final class Base64 extends Coder
 {
-    public const URL_SAFE = false;
     private const URL_REPLACE_TABLE = [
         ['+', '/', '='],
         ['-', '_', ''],
     ];
 
     private bool $urlSafe;
 
-    public function encode(string $decoded, ?bool $urlSafe = null): string
+    public function encode(string $decoded, bool|null $urlSafe = null): string
     {
-        $this->urlSafe = $urlSafe ?? self::URL_SAFE;
+        $this->urlSafe = $urlSafe ?? false;
         return parent::encode($decoded);
     }
 
@@ -35,13 +36,11 @@ protected function doEncode(string $decoded): string
 
     protected function doDecode(string $encoded): string
     {
-        $decoded = base64_decode(
+        return OptionalString::ofFalsable(base64_decode(
             str_replace(self::URL_REPLACE_TABLE[1], self::URL_REPLACE_TABLE[0], $encoded),
             strict: true,
+        ))->orElseThrow(
+            static fn () => new Exception\CoderCouldNotDecodeData(__METHOD__, $encoded),
         );
-        if ($decoded === false) {
-            throw new Exception\CouldNotDecodeData(__METHOD__, $encoded);
-        }
-        return $decoded;
     }
 }

src/Coder/Checksum.php

@@ -13,7 +13,10 @@
  */
 final class Checksum extends Coder
 {
-    public const ALGORITHM = 'crc32';
+    /**
+     * @internal public for testing purposes only
+     */
+    public const DEFAULT_ALGORITHM = 'crc32';
 
     private string $algorithm;
     private readonly Byter $byter;
@@ -23,15 +26,15 @@ public function __construct()
         $this->byter = new Byter();
     }
 
-    public function encode(string $decoded, ?string $algorithm = null): string
+    public function encode(string $decoded, string|null $algorithm = null): string
     {
-        $this->algorithm = $algorithm ?? self::ALGORITHM;
+        $this->algorithm = $algorithm ?? self::DEFAULT_ALGORITHM;
         return parent::encode($decoded);
     }
 
-    public function decode(string $encoded, ?string $algorithm = null): string
+    public function decode(string $encoded, string|null $algorithm = null): string
     {
-        $this->algorithm = $algorithm ?? self::ALGORITHM;
+        $this->algorithm = $algorithm ?? self::DEFAULT_ALGORITHM;
         return parent::decode($encoded);
     }
 
@@ -46,7 +49,7 @@ protected function doDecode(string $encoded): string
         $checksumLength = $this->byter->size(hash($this->algorithm, '', binary: true));
         [,$decoded] = $this->byter->bite($encoded, -$checksumLength);
         if ($this->doEncode($decoded) !== $encoded) {
-            throw new Exception\CouldNotDecodeData(__METHOD__, $encoded);
+            throw new Exception\CoderCouldNotDecodeData(__METHOD__, $encoded);
         }
         return $decoded;
     }

src/Coder/Coder.php

@@ -6,38 +6,43 @@
 
 use Throwable;
 
+/**
+ * @internal shared logic
+ */
 abstract class Coder implements CoderInterface
 {
     public function encode(string $decoded): string
     {
         try {
-            return $this->doEncode($decoded);
+            return @$this->doEncode($decoded);
+        } catch (Exception\CoderCouldNotEncodeData $exception) {
+            throw $exception;
         } catch (Throwable $reason) {
-            if ($reason instanceof Exception\CouldNotEncodeData) {
-                throw $reason;
-            }
-            throw new Exception\CouldNotEncodeData(__METHOD__, $decoded, $reason);
+            throw new Exception\CoderCouldNotEncodeData(__METHOD__, $decoded, $reason);
         }
     }
 
     public function decode(string $encoded): string
     {
         try {
-            return $this->doDecode($encoded);
+            return @$this->doDecode($encoded);
+        } catch (Exception\CoderCouldNotDecodeData $exception) {
+            throw $exception;
         } catch (Throwable $reason) {
-            if ($reason instanceof Exception\CouldNotDecodeData) {
-                throw $reason;
-            }
-            throw new Exception\CouldNotDecodeData(__METHOD__, $encoded, $reason);
+            throw new Exception\CoderCouldNotDecodeData(__METHOD__, $encoded, $reason);
         }
     }
 
     /**
+     * @note errors will be silenced
+     *
      * @throws Throwable
      */
     abstract protected function doEncode(string $decoded): string;
 
     /**
+     * @note errors will be silenced
+     *
      * @throws Throwable
      */
     abstract protected function doDecode(string $encoded): string;

src/Coder/CoderInterface.php

@@ -7,12 +7,12 @@
 interface CoderInterface
 {
     /**
-     * @throws Exception\CouldNotEncodeData
+     * @throws Exception\CoderCouldNotEncodeData
      */
     public function encode(string $decoded): string;
 
     /**
-     * @throws Exception\CouldNotDecodeData
+     * @throws Exception\CoderCouldNotDecodeData
      */
     public function decode(string $encoded): string;
 }

src/Coder/Exception/CouldNotDecodeData.php renamed to src/Coder/Exception/CoderCouldNotDecodeData.php

@@ -9,6 +9,6 @@
 /**
  * @extends CouldNotProcessData<string>
  */
-final class CouldNotDecodeData extends CouldNotProcessData implements CoderException
+final class CoderCouldNotDecodeData extends CouldNotProcessData implements CoderException
 {
 }