Pure PHP implementation of Google Snappy library (#613)

.github/labeler.yml

@@ -17,6 +17,8 @@ lib-parquet:
   - any: ["src/lib/parquet/**/*"]
 lib-dremel:
   - any: ["src/lib/dremel/**/*"]
+lib-snappy:
+  - any: ["src/lib/snappy/**/*"]
 
 adapter-amphp:
   - any: ["src/adapter/etl-adapter-amphp/**/*"]

.github/workflows/monorepo-split.yml

@@ -30,6 +30,8 @@ jobs:
             split_repository: 'parquet'
           - local_path: 'src/lib/dremel'
             split_repository: 'dremel'
+          - local_path: 'src/lib/snappy'
+            split_repository: 'snappy'
 
           - local_path: 'src/adapter/etl-adapter-amphp'
             split_repository: 'etl-adapter-amphp'

README.md

@@ -57,6 +57,7 @@ this will reduce the number of unnecessary dependencies in your project (less ma
   - [doctrine-dbal-bulk](src/lib/doctrine-dbal-bulk/README.md)
   - [Google Dremel algorithm](src/lib/dremel/README.md)
   - [Parquet](src/lib/parquet/README.md)
+  - [Snappy](src/lib/snappy/README.md)
 
 For example, if you want to work with JSON/CSV files here are the dependencies you will need to install: 
 

composer.json

@@ -60,7 +60,8 @@
             "build/version.php",
             "src/core/etl/src/Flow/ETL/DSL/functions.php",
             "src/lib/array-dot/src/Flow/ArrayDot/array_dot.php",
-            "src/lib/parquet/src/Flow/Parquet/functions.php"
+            "src/lib/parquet/src/Flow/Parquet/functions.php",
+            "src/lib/snappy/polifil.php"
         ],
         "psr-4": {
             "Flow\\": [
@@ -83,7 +84,8 @@
                 "src/lib/array-dot/src/Flow",
                 "src/lib/doctrine-dbal-bulk/src/Flow",
                 "src/lib/dremel/src/Flow",
-                "src/lib/parquet/src/Flow"
+                "src/lib/parquet/src/Flow",
+                "src/lib/snappy/src/Flow"
             ],
             "Flow\\Doctrine\\Bulk\\": [
                 "src/lib/doctrine-dbal-bulk/src/Flow/Doctrine/Bulk"
@@ -115,7 +117,8 @@
                 "src/lib/array-dot/tests/Flow",
                 "src/lib/doctrine-dbal-bulk/tests/Flow",
                 "src/lib/dremel/tests/Flow",
-                "src/lib/parquet/tests/Flow"
+                "src/lib/parquet/tests/Flow",
+                "src/lib/snappy/tests/Flow"
             ],
             "Flow\\Doctrine\\Bulk\\Tests\\": [
                 "src/lib/doctrine-dbal-bulk/tests/Flow/Doctrine/Bulk/Tests"
@@ -153,7 +156,8 @@
         "flow-php/etl-adapter-reactphp": "self.version",
         "flow-php/etl-adapter-text": "self.version",
         "flow-php/etl-adapter-xml": "self.version",
-        "flow-php/parquet": "self.version"
+        "flow-php/parquet": "self.version",
+        "flow-php/snappy": "self.version"
     },
     "scripts": {
         "build": [

phpunit.xml

@@ -54,6 +54,7 @@
       <directory>src/adapter/etl-adapter-xml/tests/Flow/ETL/Adapter/XML/Tests/Integration</directory>
       <directory>src/core/etl/tests/Flow/ETL/Tests/Integration</directory>
       <directory>src/lib/parquet/tests/Flow/Parquet/Tests/Integration</directory>
+      <directory>src/lib/snappy/tests/Flow/Snappy/Tests/Integration</directory>
     </testsuite>
     <testsuite name="integration-services">
       <directory>src/adapter/etl-adapter-doctrine/tests/Flow/ETL/Adapter/Doctrine/Tests/Integration</directory>

src/lib/parquet/composer.json

@@ -13,7 +13,8 @@
     "require": {
         "php": "~8.1 || ~8.2",
         "ext-bcmath": "*",
-        "flow-php/dremel": "1.x-dev"
+        "flow-php/dremel": "1.x-dev",
+        "flow-php/snappy": "1.x-dev"
     },
     "config": {
         "optimize-autoloader": true,

src/lib/parquet/src/Flow/Parquet/ParquetFile/Codec.php

@@ -4,22 +4,14 @@
 
 use Flow\Parquet\Exception\RuntimeException;
 
-if (!\function_exists('snappy_uncompress')) {
-    /** @psalm-suppress LessSpecificReturnType */
-    function snappy_uncompress(string $data) : string|false
-    {
-        throw new \Flow\ETL\Exception\RuntimeException('snappy_uncompress() is not available. Please install php-snappy extension https://github.com/kjdev/php-ext-snappy');
-    }
-}
-
 final class Codec
 {
     public function decompress(string $data, Compressions $compression) : string
     {
         /** @var false|string $result */
         $result = match ($compression) {
             Compressions::UNCOMPRESSED => $data,
-            Compressions::SNAPPY => snappy_uncompress($data),
+            Compressions::SNAPPY => \snappy_uncompress($data),
             Compressions::GZIP => \gzdecode($data),
             default => throw new RuntimeException('Compression ' . $compression->name . ' is not supported yet')
         };

src/lib/snappy/.gitattributes

@@ -0,0 +1,9 @@
+*.php text eol=lf
+
+/.github export-ignore
+/tests export-ignore
+
+/README.md export-ignore
+
+/.gitattributes export-ignore
+/.gitignore export-ignore

src/lib/snappy/CONTRIBUTING.md

@@ -0,0 +1,6 @@
+## Contributing
+
+This repo is **READ ONLY**, in order to contribute to Flow PHP project, please
+open PR against [flow](https://github.com/flow-php/flow) monorepo.
+
+Changes merged to monorepo are automatically propagated into sub repositories.

src/lib/snappy/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Flow PHP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/lib/snappy/README.md

@@ -0,0 +1,73 @@
+# Snappy
+
+Pure PHP implementation of Google [Snappy](https://github.com/google/snappy) compression algorithm.
+
+This library is a port of javascript [snappyjs](https://github.com/zhipeng-jia/snappyjs).
+Whenever it's possible it's recommended to install [PHP Extension](https://github.com/kjdev/php-ext-snappy),
+otherwise this lib will register polyfill functions. 
+
+## Installation
+
+```
+composer require flow-php/snappy:1.x@dev
+```
+
+## Usage
+
+```php
+<?php
+
+$string = 'This is some random string';
+
+echo \snappy_decompress(\snappy_compress($string)); // This is some random string
+```
+
+## Performance
+
+PHP Implementation is significantly slower than extension, below you can find a benchmark script and results:
+
+```php
+<?php
+
+include __DIR__ . '/../vendor/autoload.php';
+
+$faker = \Faker\Factory::create();
+
+$texts = [];
+for ($i = 0; $i < 10_000; $i++) {
+    $textSize = \random_int(100, 5000);
+    $texts[] = $faker->text($textSize);
+}
+
+$snappy = new \Flow\Snappy\Snappy();
+
+echo "Starting Benchmark\n\n";
+
+$flowStart = microtime(true);
+foreach ($texts as $text) {
+    if ($snappy->uncompress($snappy->compress($text)) !== $text) {
+        die('snappy flow failed');
+    }
+}
+$flowEnd = microtime(true);
+echo "Snappy Flow time: " . ($flowEnd - $flowStart) . "\n";
+
+$extStart = microtime(true);
+foreach ($texts as $text) {
+    if (\snappy_uncompress(\snappy_compress($text)) !== $text) {
+        die('snappy ext failed');
+    }
+}
+$extEnd = microtime(true);
+echo "Snappy PHP Extension time: " . ($extEnd - $extStart) . "\n";
+```
+
+Output: 
+
+```console
+$ php benchmark_snappy.php
+Starting Benchmark
+
+Snappy Flow time: 6.6838178634644
+Snappy PHP Extension time: 0.31190991401672
+```

src/lib/snappy/composer.json

@@ -0,0 +1,38 @@
+{
+    "name": "flow-php/snappy",
+    "type": "library",
+    "description": "PHP ETL - Google Snappy compression algorithm implementation",
+    "keywords": [
+        "etl",
+        "extract",
+        "transform",
+        "load",
+        "filter",
+        "snappy",
+        "algorithm",
+        "compression"
+    ],
+    "require": {
+        "php": "~8.1 || ~8.2"
+    },
+    "config": {
+        "optimize-autoloader": true,
+        "sort-packages": true
+    },
+    "license": "MIT",
+    "autoload": {
+        "psr-4": {
+            "Flow\\": [
+                "src/Flow"
+            ]
+        },
+        "files": [ "polifil.php" ]
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Flow\\": "tests/Flow"
+        }
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true
+}

src/lib/snappy/polifil.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+use Flow\Snappy\Snappy;
+
+if (!\function_exists('snappy_compress')) {
+    function snappy_compress(string $plainText) : string
+    {
+        return (new Snappy())->compress($plainText);
+    }
+}
+
+if (!\function_exists('snappy_uncompress')) {
+    function snappy_uncompress(string $compressedText) : string
+    {
+        return (new Snappy())->uncompress($compressedText);
+    }
+}
+

src/lib/snappy/src/Flow/Snappy/Snappy.php

@@ -0,0 +1,38 @@
+<?php declare(strict_types=1);
+
+namespace Flow\Snappy;
+
+final class Snappy
+{
+    public function __construct()
+    {
+    }
+
+    public function compress(string $plainText) : string
+    {
+        if ($plainText === '') {
+            return $plainText;
+        }
+
+        $byteArray = \array_values(\unpack('C*', $plainText));
+
+        $outputBuffer = [];
+        (new SnappyCompressor($byteArray))->compressToBuffer($outputBuffer);
+
+        return \pack('C*', ...$outputBuffer);
+    }
+
+    public function uncompress(string $compressedText) : string
+    {
+        if ($compressedText === '') {
+            return $compressedText;
+        }
+
+        $byteArray = \array_values(\unpack('C*', $compressedText));
+
+        $outputBuffer = [];
+        (new SnappyDecompressor($byteArray))->uncompressToBuffer($outputBuffer);
+
+        return \pack('C*', ...$outputBuffer);
+    }
+}