add generate composer script; add more tests; add docs

README.md

@@ -2,13 +2,19 @@
 
 See https://github.com/DarthSim/imgproxy.
 
+> STARTING FROM v2.0 imgproxy-php supports advanced URL generation. See below.  
+> **imgproxy-php** v2.0 is fully backwards compatible with v1.0, you should not have any issues with upgrading.  
+> If those issues still occur with you, you're welcome to file a bug report, and even more welcome to create a pull request.
+
 This is a small package which allows for generating URLs for your images that are resized by imgproxy:
 
 ```php
 $builder = new UrlBuilder("http://localhost:8080", "< your HEX key >", "< you HEX salt >");
 
 // Generate imgproxy URL for an image, resizing to 300x200 with default settings (*)
 $url = $builder->build("http://myimages.localhost/cats.jpg", 300, 200);
+
+// By default, the URL is generated in basic mode
 echo $url->toString();
 
 // Customize URL params
@@ -17,13 +23,55 @@ $url->setFit("fill")
   ->setHeight(1200)
   ->setGravity("no")
   ->setEnlarge(true);
+
+// switch to advanced URL mode with tons of extra features, superior to the basic mode:
+$url->useAdvancedMode();
+
+// set processing options:
+$url->options()->withResisingAlgorithm(ResisingAlgorithm::LINEAR)/* -> chain more with<FEATURE>() calls -> ... */;
 
 echo $url->toString();
 ```
 
 (*) default settings:
+ * Mode: basic (apparently, basci mode is deprecated by imgproxy and possibly will be removed in future release)
  * Fit: _fit_
  * Gravity: _sm_ (smart)
  * Enlarge: _0_ (do not enlarge images)
 
- Please refer to imgproxy docs for parameter descriptions and possible values.
+ Please refer to imgproxy docs for parameter descriptions and possible values.
+
+# Testing in "real life"
+
+In the root folder you will find `docker-compose.yml` file which will start `imgproxy` instance on port 8080. There is also a composer script `generate` with parameters:
+ * base : string base URL
+ * key : string IMGPROXY_KEY
+ * salt : string IMGPROXY_SALT
+ * source : string source image URL
+ * width : int width
+ * height : int height
+ * advanced (no value required)
+
+Once you started your local docker-compose stack with `docker-compose up`, you may call this script with the
+following command:
+
+```sh
+composer run-script generate -- \
+  --base <imgproxy base URL> \
+  --source <source image URL> \
+  --key <IMGPROXY_KEY> \
+  --salt <IMGPROXY_SALT>
+  --width <width> \
+  --height <height> \
+  --advanced
+
+# example:  
+composer run-script generate -- \
+  --base http://localhost:8080 \
+  --source http://upload.wikimedia.org/wikipedia/commons/thumb/d/d3/Cailliau_Abramatic_Berners-Lee_10_years_WWW_consortium.png/330px-Cailliau_Abramatic_Berners-Lee_10_years_WWW_consortium.png \
+  --key 943b421c9eb07c830af81030552c86009268de4e532ba2ee2eab8247c6da0881 \
+  --salt 520f986b998545b4785e0defbc4f3c1203f22de2374a3d53cb7a7fe9fea309c5
+```
+
+Hear, the KEY & SALT are valid for the imgproxy instance started by provided `docker-compose.yml`.
+You can also test URL generation for arbitrary custom imgproxy installation by providing relevant `base`, `key` & `salt`. Happy testing!

composer.json

@@ -24,5 +24,8 @@
         "psr-4": {
             "Imgproxy\\Test\\": "test/"
         }
+    },
+    "scripts": {
+        "generate": "Imgproxy\\CLI::generate"
     }
 }

docker-compose.yml

@@ -0,0 +1,12 @@
+version: "3.7"
+services:
+  imgproxy:
+    image: darthsim/imgproxy:latest
+    environment:
+      IMGPROXY_KEY: "943b421c9eb07c830af81030552c86009268de4e532ba2ee2eab8247c6da0881"
+      IMGPROXY_SALT: "520f986b998545b4785e0defbc4f3c1203f22de2374a3d53cb7a7fe9fea309c5"
+      IMGPROXY_LOCAL_FILESYSTEM_ROOT: "/opt/images"
+    ports:
+      - 8080:8080
+    volumes:
+      - ./test/sample/sample_640×426.jpeg:/opt/images/file.jpg

src/CLI.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Imgproxy;
+
+use Composer\Script\Event;
+
+class CLI
+{
+    public static function generate(Event $event)
+    {
+        $opts = $event->getArguments();
+        $base = null;
+        $key = null;
+        $salt = null;
+        $source = null;
+        $width = 0;
+        $height = 0;
+        $advanced = false;
+        for ($i = 0; $i < count($opts); $i++) {
+            $name = $opts[$i];
+            $name = ltrim($name, "-");
+            switch ($name) {
+                case "base":
+                    $base = $opts[++$i];
+                    break;
+                case "key":
+                    $key = $opts[++$i];
+                    break;
+                case "salt":
+                    $salt = $opts[++$i];
+                    break;
+                case "source":
+                    $source = $opts[++$i];
+                    break;
+                case "width":
+                    $width = $opts[++$i];
+                    break;
+                case "height":
+                    $height = $opts[++$i];
+                    break;
+                case "advanced":
+                    $advanced = true;
+                    break;
+                default:
+                    break;
+            }
+        }
+        $builder = new UrlBuilder($base, $key, $salt);
+        $url = new Url($builder, $source, $width, $height);
+        if ($advanced) {
+            $url->useAdvancedMode();
+        }
+        echo $url->toString() . "\n";
+    }
+}

src/Url.php

@@ -160,7 +160,7 @@ public function setGravity(string $gravity): Url
     public function setEnlarge(bool $enlarge): Url
     {
         $this->enlarge = $enlarge;
-        $enlarge ? $this->options->withEnlarge() : $this->options->withoutEnlarge();
+        $enlarge ? $this->options->withEnlarge() : $this->options->unset(ProcessingOption::ENLARGE);
         return $this;
     }
 
@@ -171,7 +171,7 @@ public function setEnlarge(bool $enlarge): Url
     public function setExtension(?string $extension): Url
     {
         $this->extension = $extension;
-        $extension ? $this->options->withFormat($extension) : $this->options->withoutFormat();
+        $extension ? $this->options->withFormat($extension) : $this->options->unset(ProcessingOption::FORMAT);
         return $this;
     }
 

test/UrlTest.php

@@ -33,13 +33,40 @@ public function testUnsignedPathLegacyMode(string $url, string $fit, int $w, int
         $this->assertEquals($expected, $url->unsignedPath());
     }
 
+    /**
+     * @param string $fit
+     * @param int $w
+     * @param int $h
+     * @param string $gravity
+     * @param bool $enlarge
+     * @param string $expected
+     * @dataProvider provideUnsignedPathAdvancedModeInput
+     */
+    public function testUnsignedPathAnvancedMode(string $url, string $fit, int $w, int $h, string $gravity, bool $enlarge, string $expected)
+    {
+        $url = new Url($this->secureUrlBuilder(), $url, $w, $h);
+        $url->useAdvancedMode()
+            ->setFit($fit)
+            ->setGravity($gravity)
+            ->setEnlarge($enlarge);
+        $this->assertEquals($expected, $url->unsignedPath());
+    }
+
     public function testToString()
     {
         $url = new Url($this->secureUrlBuilder(), self::IMAGE_URL, 300, 200);
         $expected = self::BASE_URL . "/-o6q11Q3DrNtMnCz_bZQzPdDxrGgx9BfVqQBbndAOwo/fit/300/200/sm/0/bG9jYWw6Ly8vZmlsZS5qcGc.jpg";
         $this->assertEquals($expected, $url->toString());
     }
 
+    public function testToStringAdvancedMode()
+    {
+        $url = new Url($this->secureUrlBuilder(), self::IMAGE_URL, 300, 200);
+        $url->useAdvancedMode();
+        $expected = self::BASE_URL . "/FF5I9WSLqeGP7H7REezXC8lYm46vdk9G3KCgqo-36hY/w:300/h:200/bG9jYWw6Ly8vZmlsZS5qcGc.jpg";
+        $this->assertEquals($expected, $url->toString());
+    }
+
     public function testSignedPath()
     {
         $url = new Url($this->secureUrlBuilder(), self::IMAGE_URL, 300, 200);
@@ -137,4 +164,73 @@ public function provideUnsignedPathLegacyModeInput()
             ],
         ];
     }
+
+    public function provideUnsignedPathAdvancedModeInput()
+    {
+        return [
+            [
+                self::IMAGE_URL,
+                "fit",
+                300,
+                200,
+                "sm",
+                false,
+                "/w:300/h:200/rt:fit/g:sm/bG9jYWw6Ly8vZmlsZS5qcGc.jpg"
+            ],
+            [
+                self::IMAGE_URL,
+                "fill",
+                300,
+                200,
+                "sm",
+                false,
+                "/w:300/h:200/rt:fill/g:sm/bG9jYWw6Ly8vZmlsZS5qcGc.jpg"
+            ],
+            [
+                self::IMAGE_URL,
+                "fit",
+                400,
+                200,
+                "sm",
+                false,
+                "/w:400/h:200/rt:fit/g:sm/bG9jYWw6Ly8vZmlsZS5qcGc.jpg"
+            ],
+            [
+                self::IMAGE_URL,
+                "fit",
+                300,
+                300,
+                "sm",
+                false,
+                "/w:300/h:300/rt:fit/g:sm/bG9jYWw6Ly8vZmlsZS5qcGc.jpg"
+            ],
+            [
+                self::IMAGE_URL,
+                "fit",
+                300,
+                200,
+                "no",
+                false,
+                "/w:300/h:200/rt:fit/g:no:0:0/bG9jYWw6Ly8vZmlsZS5qcGc.jpg"
+            ],
+            [
+                self::IMAGE_URL,
+                "fit",
+                300,
+                200,
+                "sm",
+                true,
+                "/w:300/h:200/rt:fit/g:sm/el:1/bG9jYWw6Ly8vZmlsZS5qcGc.jpg"
+            ],
+            [
+                self::IMAGE_URL_WITH_QUERY,
+                "fit",
+                1200,
+                900,
+                "sm",
+                false,
+                "/w:1200/h:900/rt:fit/g:sm/aHR0cDovL3N0b3JhZ2UucmVjcm0ucnUvU3RhdGljLzEzMDgzXzg0ODNiOS8xMS9XU0lNRy8xMjAwXzc5NV9JX01DX2pwZ19XL3Jlc291cmNlcy9wcm9wZXJ0aWVzLzE2NjgvcGljdHVyZV8wMDA5LmpwZz9GODBBNjRGRjFCNkU4NTg1OTA5MzM2NDkwRjc4QTFFNA.jpg"
+            ],
+        ];
+    }
 }