Merge pull request #2 from petrknap/xz-wrapper

Implemented xz compression and decompression

Author: petrknap

.github/workflows/docker.yaml

@@ -0,0 +1,13 @@
+name: composer ci-script
+
+on:
+  pull_request:
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: docker build -t $GITHUB_REPOSITORY:$GITHUB_SHA .
+      - name: Run composer ci-script
+        run: docker run $GITHUB_REPOSITORY:$GITHUB_SHA composer ci-script

.molireali

@@ -4,6 +4,7 @@ dockerfile php 8.1-cli
 docker-scripts petrknap/php-xz-utils
 donation
 github-templates
+github-workflow docker "composer ci-script"
 github-workflow linter-docker
 github-workflow linter-php 8.1
 license LGPL-3.0-or-later

README.md

@@ -1,6 +1,11 @@
 # XZ Utils (wrapper)
 
 User-friendly wrapper for XZ Utils, providing simplified and streamlined access to powerful data compression and decompression tools.
+For ease of use, you can use the approach known from the [compression extensions](https://www.php.net/manual/en/refs.compression.php):
+```php
+$encoded = xzencode(b'data') or throw new Exception();
+$decoded = xzdecode($encoded) or throw new Exception();
+```
 
 ---
 

composer.json

@@ -3,7 +3,10 @@
   "autoload": {
     "psr-4": {
       "PetrKnap\\XzUtils\\": "src"
-    }
+    },
+    "files": [
+      "src/ext-xz.php"
+    ]
   },
   "autoload-dev": {
     "psr-4": {
@@ -32,7 +35,9 @@
   "license": "LGPL-3.0-or-later",
   "name": "petrknap/xz-utils",
   "require": {
-    "php": ">=8.1"
+    "php": ">=8.1",
+    "petrknap/shorts": "^3.0",
+    "symfony/process": "^6.4"
   },
   "require-dev": {
     "nunomaduro/phpinsights": "^2.11",

src/Exception/Exception.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\XzUtils\Exception;
+
+use Throwable;
+
+/**
+ * @internal root exception
+ */
+interface Exception extends Throwable
+{
+}

src/Exception/XzCouldNotCompressData.php

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

src/Exception/XzCouldNotDecompressData.php

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

src/Exception/XzException.php

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

src/Xz.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\XzUtils;
+
+use Symfony\Component\Process\Exception\ProcessFailedException;
+use Symfony\Component\Process\Process;
+use Throwable;
+
+final class Xz
+{
+    /**
+     * @param array<non-empty-string> $options
+     *
+     * @throws Exception\XzCouldNotCompressData
+     */
+    public function compress(
+        string $data,
+        int|null $compressionPreset = null,
+        array $options = [],
+    ): string {
+        $command = [
+            'xz',
+            '--compress',
+        ];
+        if ($compressionPreset !== null) {
+            $command[] = '-' . $compressionPreset;
+        }
+        try {
+            return self::run(array_merge($command, $options), $data);
+        } catch (Throwable $reason) {
+            throw new Exception\XzCouldNotCompressData(__METHOD__, $data, $reason);
+        }
+    }
+
+    /**
+     * @param array<non-empty-string> $options
+     *
+     * @throws Exception\XzCouldNotDecompressData
+     */
+    public function decompress(
+        string $data,
+        array $options = [],
+    ): string {
+        $command = [
+            'xz',
+            '--decompress',
+        ];
+        try {
+            return self::run(array_merge($command, $options), $data);
+        } catch (Throwable $reason) {
+            throw new Exception\XzCouldNotDecompressData(__METHOD__, $data, $reason);
+        }
+    }
+
+    /**
+     * @param non-empty-array<non-empty-string> $command
+     *
+     * @throws ProcessFailedException
+     *
+     * @todo move it to another package
+     */
+    private static function run(array $command, string $input): string
+    {
+        $process = new Process($command);
+        $process->setInput($input);
+        $process->run();
+        if (!$process->isSuccessful()) {
+            throw new ProcessFailedException($process);
+        }
+        return $process->getOutput();
+    }
+}

src/ext-xz.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+if (!function_exists('xzencode')) {
+    /**
+     * @see gzencode()
+     * @see PetrKnap\XzUtils\Xz::compress()
+     */
+    function xzencode(string $data, int|null $compressionPreset = null): string|false
+    {
+        try {
+            return (new PetrKnap\XzUtils\Xz())->compress($data, $compressionPreset);
+        } catch (Throwable) {
+            return false;
+        }
+    }
+}
+
+if (!function_exists('xzdecode')) {
+    /**
+     * @see gzdecode()
+     * @see PetrKnap\XzUtils\Xz::decompress()
+     */
+    function xzdecode(string $data): string|false
+    {
+        try {
+            return (new PetrKnap\XzUtils\Xz())->decompress($data);
+        } catch (Throwable) {
+            return false;
+        }
+    }
+}

tests/ReadmeTest.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\XzUtils;
+
+use PetrKnap\Shorts\PhpUnit\MarkdownFileTestInterface;
+use PetrKnap\Shorts\PhpUnit\MarkdownFileTestTrait;
+use PHPUnit\Framework\TestCase;
+
+final class ReadmeTest extends TestCase implements MarkdownFileTestInterface
+{
+    use MarkdownFileTestTrait;
+
+    public static function getPathToMarkdownFile(): string
+    {
+        return __DIR__ . '/../README.md';
+    }
+
+    public static function getExpectedOutputsOfPhpExamples(): iterable
+    {
+        return [
+            'ext-xz' => '',
+        ];
+    }
+}

tests/XzTest.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PetrKnap\XzUtils;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\TestCase;
+
+final class XzTest extends TestCase
+{
+    #[DataProvider('data')]
+    public function testCompressesData(string $decompressed, string $compressed, int|null $compressionPreset): void
+    {
+        self::assertSame(
+            bin2hex($compressed),
+            bin2hex((new Xz())->compress($decompressed, $compressionPreset)),
+        );
+    }
+
+    #[DataProvider('data')]
+    public function testDecompressesData(string $decompressed, string $compressed): void
+    {
+        self::assertSame(
+            bin2hex($decompressed),
+            bin2hex((new Xz())->decompress($compressed)),
+        );
+    }
+
+    public static function data(): array
+    {
+        $decompressed = base64_decode('h/J4V2gAK1njeEOqyTiTjg==');
+        return [
+            'default compression preset' => [
+                $decompressed,
+                base64_decode('/Td6WFoAAATm1rRGAgAhARYAAAB0L+WjAQAPh/J4V2gAK1njeEOqyTiTjgDL7VTjlSH1vwABKBDlC2xgH7bzfQEAAAAABFla'),
+                null,
+            ],
+            'compression preset 0' => [
+                $decompressed,
+                base64_decode('/Td6WFoAAATm1rRGAgAhAQwAAACPmEGcAQAPh/J4V2gAK1njeEOqyTiTjgDL7VTjlSH1vwABKBDlC2xgH7bzfQEAAAAABFla'),
+                0,
+            ],
+            'compression preset 9' => [
+                $decompressed,
+                base64_decode('/Td6WFoAAATm1rRGAgAhARwAAAAQz1jMAQAPh/J4V2gAK1njeEOqyTiTjgDL7VTjlSH1vwABKBDlC2xgH7bzfQEAAAAABFla'),
+                9,
+            ],
+        ];
+    }
+}