Add support of "auto" value for start_offset transformation parameter (#123)

* Add support of "auto" value for `start_offset` transformation parameter

Author: shedar

src/Cloudinary.php

@@ -481,11 +481,11 @@ public static function generate_transformation_string(&$options = array())
         $dpr = Cloudinary::option_consume($options, "dpr", Cloudinary::config_get("dpr"));
 
         $duration = Cloudinary::norm_range_value(Cloudinary::option_consume($options, "duration"));
-        $start_offset = Cloudinary::norm_range_value(Cloudinary::option_consume($options, "start_offset"));
+        $start_offset = Cloudinary::norm_auto_range_value(Cloudinary::option_consume($options, "start_offset"));
         $end_offset = Cloudinary::norm_range_value(Cloudinary::option_consume($options, "end_offset"));
         $offset = Cloudinary::split_range(Cloudinary::option_consume($options, "offset"));
         if (!empty($offset)) {
-            $start_offset = Cloudinary::norm_range_value($offset[0]);
+            $start_offset = Cloudinary::norm_auto_range_value($offset[0]);
             $end_offset = Cloudinary::norm_range_value($offset[1]);
         }
 
@@ -856,6 +856,14 @@ private static function norm_range_value($value)
         return $matches['value'] . $modifier;
     }
 
+    private static function norm_auto_range_value($value)
+    {
+        if ($value == 'auto') {
+            return $value;
+        }
+        return self::norm_range_value($value);
+    }
+
     private static function process_video_codec_param($param)
     {
         $out_param = $param;

tests/CloudinaryTest.php

@@ -12,6 +12,17 @@ class CloudinaryTest extends TestCase
     const DEFAULT_UPLOAD_PATH = 'http://res.cloudinary.com/test123/image/upload/';
     const VIDEO_UPLOAD_PATH = 'http://res.cloudinary.com/test123/video/upload/';
 
+    private $range_test_pairs = [
+        // integer values
+        ["200", "200"], [200, "200"], [0, "0"],
+        // float values
+        ["200.0", "200.0"], [200.0, "200.0"], [200.123, "200.123"], [200.123000, "200.123"], [0.0, "0.0"],
+        //percent values
+        ["20p", "20p"], ["20P", "20p"], ["20%", "20p"], ["20.5%", "20.5p"],
+        // invalid values
+        ["p", null], ["", null], [null, null], ["non_auto", null],
+    ];
+
     private $original_user_platform;
 
     public function setUp()
@@ -834,26 +845,20 @@ public function test_norm_range_value()
     {
         $method = new ReflectionMethod('Cloudinary', 'norm_range_value');
         $method->setAccessible(true);
-        // should parse integer range values
-        $this->assertEquals($method->invoke(null, "200"), "200");
-        $this->assertEquals($method->invoke(null, 200), "200");
-        $this->assertEquals($method->invoke(null, 0), "0");
-        // should parse float range values
-        $this->assertEquals($method->invoke(null, "200.0"), "200.0");
-        $this->assertEquals($method->invoke(null, 200.0), "200.0");
-        $this->assertEquals($method->invoke(null, 200.00), "200.0");
-        $this->assertEquals($method->invoke(null, 200.123), "200.123");
-        $this->assertEquals($method->invoke(null, 200.123000), "200.123");
-        $this->assertEquals($method->invoke(null, 0.0), "0.0");
-        // should parse a percent range value
-        $this->assertEquals($method->invoke(null, "20p"), "20p");
-        $this->assertEquals($method->invoke(null, "20P"), "20p");
-        $this->assertEquals($method->invoke(null, "20%"), "20p");
-        $this->assertEquals($method->invoke(null, "20.5%"), "20.5p");
-        // should handle invalid input
-        $this->assertNull($method->invoke(null, "p"));
-        $this->assertNull($method->invoke(null, ""));
-        $this->assertNull($method->invoke(null, null));
+        foreach ($this->range_test_pairs as $pair) {
+            $this->assertEquals($method->invoke(null, $pair[0]), $pair[1]);
+        }
+        $this->assertNull($method->invoke(null, "auto"), "Shouldn't support 'auto' value");
+    }
+
+    public function test_norm_auto_range_value()
+    {
+        $method = new ReflectionMethod('Cloudinary', 'norm_auto_range_value');
+        $method->setAccessible(true);
+        foreach ($this->range_test_pairs as $pair) {
+            $this->assertEquals($method->invoke(null, $pair[0]), $pair[1]);
+        }
+        $this->assertEquals($method->invoke(null, "auto"), "auto", "Should support 'auto' value");
     }
 
     public function test_video_codec()
@@ -954,6 +959,12 @@ public function test_start_offset()
             array('resource_type' => 'video', 'start_offset' => '35%'),
             CloudinaryTest::VIDEO_UPLOAD_PATH . "so_35p/video_id"
         );
+        // should support auto select of a suitable frame from the first few seconds of a video
+        $this->cloudinary_url_assertion(
+            "video_id",
+            array('resource_type' => 'video', 'start_offset' => 'auto'),
+            CloudinaryTest::VIDEO_UPLOAD_PATH . "so_auto/video_id"
+        );
     }
 
     public function test_end_offset()