feat: coders with support for base64 and zlib

Author: petrknap

README.md

@@ -1 +1,20 @@
-# php-binary
+# 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).
+
+```php
+use PetrKnap\Binary\Binary;
+
+$data = base64_decode('hmlpFnFwbchsoQARSibVpfbWVfuwAHLbGxjFl9eC8fiGaWkWcXBtyGyhABFKJtWl9tZV+7AActsbGMWX14Lx+A==');
+$encoded = Binary::encode($data)->zlib()->base64(urlSafe: true)->getData();
+$decoded = Binary::decode($encoded)->base64()->zlib()->getData();
+
+printf('Data was coded into `%s` %s.', $encoded, $decoded === $data ? 'successfully' : 'unsuccessfully');
+```
+
+---
+
+Run `composer require petrknap/binary` to install it.
+You can [support this project via donation](https://petrknap.github.io/donate.html).
+The project is licensed under [the terms of the `LGPL-3.0-or-later`](./COPYING.LESSER).

composer.json

@@ -1,5 +1,5 @@
 {
-  "WARNING": "This file is updated automatically. All keys will be overwritten, except of 'conflict', 'keywords', 'require', 'require-dev' and 'scripts'.",
+  "WARNING": "This file is updated automatically. All keys will be overwritten, except of 'conflict', 'keywords', 'require', 'require-dev', 'scripts' and 'suggest'.",
   "autoload": {
     "psr-4": {
       "PetrKnap\\Binary\\": "src"
@@ -14,7 +14,7 @@
     "allow-plugins": false,
     "sort-packages": true
   },
-  "description": "Simple util for work with binary in PHP",
+  "description": "Library for work with binaries",
   "funding": [
     {
       "type": "other",
@@ -24,16 +24,21 @@
   "homepage": "https://github.com/petrknap/php-binary",
   "keywords": [
     "binary",
+    "helper",
+    "base64",
     "encoder",
     "decoder",
-    "helper"
+    "zlib",
+    "compression",
+    "decompression"
   ],
   "license": "LGPL-3.0-or-later",
   "name": "petrknap/binary",
   "require": {
     "php": ">=8.1"
   },
   "require-dev": {
+    "ext-zlib": "*",
     "nunomaduro/phpinsights": "^2.11",
     "petrknap/shorts": "^1.3",
     "phpstan/phpstan": "^1.10",
@@ -46,11 +51,14 @@
       "phpcs --colors --standard=PSR12 --exclude=PSR12.Files.OpenTag,PSR12.Files.FileHeader,Generic.Files.LineLength src tests",
       "phpstan analyse --level max src",
       "phpstan analyse --level 5 tests",
-      "phpinsights analyse src"
+      "phpinsights analyse src --ansi --no-interaction"
     ],
     "ci-script": [
       "@validate",
       "@test"
     ]
+  },
+  "suggest": {
+    "ext-zlib": "Required to compress data"
   }
 }

src/Binary.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+final class Binary
+{
+    public static function encode(string $data): Encoder
+    {
+        return new Encoder($data);
+    }
+
+    public static function decode(string $data): Decoder
+    {
+        return new Decoder($data);
+    }
+}

src/Coder.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+/**
+ * @phpstan-consistent-constructor override {@see self::create()} if not
+ *
+ * @implements CoderInterface<Exception\CouldNotCodeData>
+ */
+abstract class Coder implements CoderInterface
+{
+    protected const BASE64_URL_SAFE_MAP = [
+        ['+', '/', '='],
+        ['-', '_', ''],
+    ];
+
+    public function __construct(
+        protected readonly string $data,
+    ) {
+    }
+
+    public function getData(): string
+    {
+        return $this->data;
+    }
+
+    protected static function create(self $coder, string $data): static
+    {
+        return new static($data);
+    }
+}

src/CoderInterface.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+/**
+ * @template TExceptionCouldNotCodeData of Exception\CouldNotCodeData
+ */
+interface CoderInterface
+{
+    public function getData(): string;
+
+    /**
+     * {@see base64_encode()}/{@see base64_decode()} data
+     *
+     * @link https://en.wikipedia.org/wiki/Base64
+     *
+     * @throws TExceptionCouldNotCodeData
+     */
+    public function base64(): static;
+
+    /**
+     * {@see zlib_encode()}/{@see zlib_decode()} data
+     *
+     * @link https://en.wikipedia.org/wiki/Zlib
+     *
+     * @throws TExceptionCouldNotCodeData
+     */
+    public function zlib(): static;
+}

src/Decoder.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+use Throwable;
+
+class Decoder extends Coder implements DecoderInterface
+{
+    public function base64(): static
+    {
+        try {
+            $decoded = base64_decode(
+                str_replace(self::BASE64_URL_SAFE_MAP[1], self::BASE64_URL_SAFE_MAP[0], $this->data),
+                strict: true,
+            );
+            if ($decoded === false) {
+                throw new Exception\CouldNotDecodeData($this, __METHOD__);
+            }
+            return static::create($this, $decoded);
+        } catch (Throwable $reason) {
+            throw new Exception\CouldNotDecodeData($this, __METHOD__, $reason);
+        }
+    }
+
+    public function zlib(int $maxLength = self::ZLIB_MAX_LENGTH): static
+    {
+        try {
+            $decoded = zlib_decode($this->data, $maxLength);
+            if ($decoded === false) {
+                throw new Exception\CouldNotDecodeData($this, __METHOD__);
+            }
+            return static::create($this, $decoded);
+        } catch (Throwable $reason) {
+            throw new Exception\CouldNotDecodeData($this, __METHOD__, $reason);
+        }
+    }
+}

src/DecoderInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+/**
+ * @extends CoderInterface<Exception\CouldNotDecodeData>
+ */
+interface DecoderInterface extends CoderInterface
+{
+    public const ZLIB_MAX_LENGTH = 0;
+
+    public function zlib(int $maxLength = self::ZLIB_MAX_LENGTH): static;
+}

src/Encoder.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+use Throwable;
+
+class Encoder extends Coder implements EncoderInterface
+{
+    public function base64(bool $urlSafe = self::BASE64_URL_SAFE): static
+    {
+        try {
+            $encoded = base64_encode($this->data);
+            if ($urlSafe) {
+                $encoded = str_replace(self::BASE64_URL_SAFE_MAP[0], self::BASE64_URL_SAFE_MAP[1], $encoded);
+            }
+            return static::create($this, $encoded);
+        } catch (Throwable $reason) {
+            throw new Exception\CouldNotEncodeData($this, __METHOD__, $reason);
+        }
+    }
+
+    public function zlib(int $encoding = self::ZLIB_ENCODING, int $level = self::ZLIB_LEVEL): static
+    {
+        try {
+            $encoded = zlib_encode($this->data, $encoding, $level);
+            if ($encoded === false) {
+                throw new Exception\CouldNotEncodeData($this, __METHOD__);
+            }
+            return static::create($this, $encoded);
+        } catch (Throwable $reason) {
+            throw new Exception\CouldNotEncodeData($this, __METHOD__, $reason);
+        }
+    }
+}

src/EncoderInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\Binary;
+
+/**
+ * @extends CoderInterface<Exception\CouldNotEncodeData>
+ */
+interface EncoderInterface extends CoderInterface
+{
+    public const BASE64_URL_SAFE = false;
+    public const ZLIB_ENCODING = ZLIB_ENCODING_RAW;
+    public const ZLIB_LEVEL = -1;
+
+    public function base64(bool $urlSafe = self::BASE64_URL_SAFE): static;
+
+    public function zlib(int $encoding = self::ZLIB_ENCODING, int $level = self::ZLIB_LEVEL): static;
+}

src/Exception/BinaryException.php

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