Progress Tracker for MultipartUploader & MultipartCopy

src/Multipart/AbstractUploader.php

@@ -147,4 +147,4 @@ protected function getNumberOfParts($partSize)
         }
         return null;
     }
-}
+}

src/Multipart/UploadState.php

@@ -13,6 +13,18 @@ class UploadState
     const INITIATED = 1;
     const COMPLETED = 2;
 
+    protected $progressBar = [
+        "Transfer initiated...\n|                    | 0.0%\n",
+        "|==                  | 12.5%\n",
+        "|=====               | 25.0%\n",
+        "|=======             | 37.5%\n",
+        "|==========          | 50.0%\n",
+        "|============        | 62.5%\n",
+        "|===============     | 75.0%\n",
+        "|=================   | 87.5%\n",
+        "|====================| 100.0%\nTransfer complete!\n"
+    ];
+
     /** @var array Params used to identity the upload. */
     private $id;
 
@@ -25,6 +37,9 @@ class UploadState
     /** @var int Identifies the status the upload. */
     private $status = self::CREATED;
 
+    /** @var array Thresholds for progress of the upload. */
+    private $progressThresholds = [];
+
     /**
      * @param array $id Params used to identity the upload.
      */
@@ -45,7 +60,7 @@ public function getId()
     }
 
     /**
-     * Set's the "upload_id", or 3rd part of the upload's ID. This typically
+     * Sets the "upload_id", or 3rd part of the upload's ID. This typically
      * only needs to be done after initiating an upload.
      *
      * @param string $key   The param key of the upload_id.
@@ -76,6 +91,47 @@ public function setPartSize($partSize)
         $this->partSize = $partSize;
     }
 
+    /**
+     * Sets the 1/8th thresholds array. $totalSize is only sent if
+     * 'track_upload' is true.
+     *
+     * @param $totalSize numeric Size of object to upload.
+     *
+     * @return array
+     */
+    public function setProgressThresholds($totalSize)
+    {
+        if(!is_numeric($totalSize)) {
+            throw new \InvalidArgumentException('The total size of the upload must be a number.');
+        }
+
+        $this->progressThresholds[0] = 0;
+        for ($i=1;$i<=8;$i++) {
+            $this->progressThresholds []= round($totalSize*($i/8));
+        }
+        return $this->progressThresholds;
+    }
+
+    /**
+     * Prints progress of upload.
+     *
+     * @param $totalUploaded numeric Size of upload so far.
+     */
+    public function displayProgress($totalUploaded)
+    {
+        if(!is_numeric($totalUploaded)) {
+            throw new \InvalidArgumentException('The size of the bytes being uploaded must be a number.');
+        }
+
+        while (!empty($this->progressThresholds)
+                && !empty($this->progressBar)
+                && $totalUploaded >= $this->progressThresholds[0])
+        {
+            echo array_shift($this->progressBar);
+            array_shift($this->progressThresholds);
+        }
+    }
+
     /**
      * Marks a part as being uploaded.
      *
@@ -108,7 +164,6 @@ public function hasPartBeenUploaded($partNumber)
     public function getUploadedParts()
     {
         ksort($this->uploadedParts);
-
         return $this->uploadedParts;
     }
 
@@ -118,6 +173,7 @@ public function getUploadedParts()
      * @param int $status Status is an integer code defined by the constants
      *                    CREATED, INITIATED, and COMPLETED on this class.
      */
+
     public function setStatus($status)
     {
         $this->status = $status;
@@ -142,4 +198,4 @@ public function isCompleted()
     {
         return $this->status === self::COMPLETED;
     }
-}
+}

src/S3/MultipartCopy.php

@@ -52,6 +52,8 @@ class MultipartCopy extends AbstractUploadManager
      *   options are ignored.
      * - source_metadata: (Aws\ResultInterface) An object that represents the
      *   result of executing a HeadObject command on the copy source.
+     * - track_upload: (boolean) Set true to track status in 1/8th increments
+     *   for upload.
      *
      * @param S3ClientInterface $client Client used for the upload.
      * @param string|array $source Location of the data to be copied (in the
@@ -75,6 +77,12 @@ public function __construct(
             $client,
             array_change_key_case($config) + ['source_metadata' => null]
         );
+
+        if (isset($config['track_upload']) && $config['track_upload']) {
+            $this->getState()->setProgressThresholds(
+                $this->sourceMetadata["ContentLength"]
+            );
+        }
     }
 
     /**

src/S3/MultipartUploader.php

@@ -55,6 +55,8 @@ class MultipartUploader extends AbstractUploader
      *   of the multipart upload and that is used to resume a previous upload.
      *   When this option is provided, the `bucket`, `key`, and `part_size`
      *   options are ignored.
+     * - track_upload: (boolean) Set true to track status in 1/8th increments
+     *   for upload.
      *
      * @param S3ClientInterface $client Client used for the upload.
      * @param mixed             $source Source of the data to upload.
@@ -70,6 +72,10 @@ public function __construct(
             'key'    => null,
             'exception_class' => S3MultipartUploadException::class,
         ]);
+
+        if (isset($config['track_upload']) && $config['track_upload']) {
+            $this->getState()->setProgressThresholds($this->source->getSize());
+        }
     }
 
     protected function loadUploadWorkflowInfo()

src/S3/MultipartUploadingTrait.php

@@ -7,6 +7,8 @@
 
 trait MultipartUploadingTrait
 {
+    private $uploadedBytes = 0;
+
     /**
      * Creates an UploadState object for a multipart upload by querying the
      * service for the specified upload's information.
@@ -55,6 +57,11 @@ protected function handleResult(CommandInterface $command, ResultInterface $resu
             'PartNumber' => $command['PartNumber'],
             'ETag'       => $this->extractETag($result),
         ]);
+
+        // Updates counter for uploaded bytes.
+        $this->uploadedBytes += $command["ContentLength"];
+        // Sends uploaded bytes to progress tracker.
+        $this->getState()->displayProgress($this->uploadedBytes);
     }
 
     abstract protected function extractETag(ResultInterface $result);

tests/Multipart/UploadStateTest.php

@@ -2,7 +2,7 @@
 namespace Aws\Test\Multipart;
 
 use Aws\Multipart\UploadState;
-use PHPUnit\Framework\TestCase;
+use Yoast\PHPUnitPolyfills\TestCases\TestCase;
 
 /**
  * @covers Aws\Multipart\UploadState
@@ -70,4 +70,158 @@ public function testSerializationWorks()
         $this->assertTrue($newState->isInitiated());
         $this->assertArrayHasKey('foo', $newState->getId());
     }
-}
+
+    public function testEmptyUploadStateOutputWithConfigFalse()
+    {
+        $state = new UploadState([]);
+        $state->displayProgress(13);
+        $this->expectOutputString('');
+    }
+
+    /**
+     * @dataProvider getDisplayProgressCases
+     */
+    public function testDisplayProgressPrintsProgress(
+        $totalSize,
+        $totalUploaded,
+        $progressBar
+    ) {
+        $state = new UploadState([]);
+        $state->setProgressThresholds($totalSize);
+        $state->displayProgress($totalUploaded);
+
+        $this->expectOutputString($progressBar);
+    }
+
+    public function getDisplayProgressCases()
+    {
+        $progressBar = ["Transfer initiated...\n|                    | 0.0%\n",
+                        "|==                  | 12.5%\n",
+                        "|=====               | 25.0%\n",
+                        "|=======             | 37.5%\n",
+                        "|==========          | 50.0%\n",
+                        "|============        | 62.5%\n",
+                        "|===============     | 75.0%\n",
+                        "|=================   | 87.5%\n",
+                        "|====================| 100.0%\nTransfer complete!\n"];
+        return [
+            [100000, 0, $progressBar[0]],
+            [100000, 12499, $progressBar[0]],
+            [100000, 12500, "{$progressBar[0]}{$progressBar[1]}"],
+            [100000, 24999, "{$progressBar[0]}{$progressBar[1]}"],
+            [100000, 25000, "{$progressBar[0]}{$progressBar[1]}{$progressBar[2]}"],
+            [100000, 37499, "{$progressBar[0]}{$progressBar[1]}{$progressBar[2]}"],
+            [
+                100000,
+                37500,
+                "{$progressBar[0]}{$progressBar[1]}{$progressBar[2]}{$progressBar[3]}"
+            ],
+            [
+                100000,
+                49999,
+                "{$progressBar[0]}{$progressBar[1]}{$progressBar[2]}{$progressBar[3]}"
+            ],
+            [
+                100000,
+                50000,
+                "{$progressBar[0]}{$progressBar[1]}{$progressBar[2]}{$progressBar[3]}{$progressBar[4]}"
+            ],
+            [
+                100000,
+                62499,
+                "{$progressBar[0]}{$progressBar[1]}{$progressBar[2]}{$progressBar[3]}{$progressBar[4]}"
+            ],
+            [
+                100000,
+                62500,
+                "{$progressBar[0]}{$progressBar[1]}{$progressBar[2]}{$progressBar[3]}{$progressBar[4]}" .
+                "{$progressBar[5]}"
+            ],
+            [
+                100000,
+                74999,
+                "{$progressBar[0]}{$progressBar[1]}{$progressBar[2]}{$progressBar[3]}{$progressBar[4]}" .
+                "{$progressBar[5]}"
+            ],
+            [
+                100000,
+                75000,
+                "{$progressBar[0]}{$progressBar[1]}{$progressBar[2]}{$progressBar[3]}{$progressBar[4]}" .
+                "{$progressBar[5]}{$progressBar[6]}"
+            ],
+            [
+                100000,
+                87499,
+                "{$progressBar[0]}{$progressBar[1]}{$progressBar[2]}{$progressBar[3]}{$progressBar[4]}" .
+                "{$progressBar[5]}{$progressBar[6]}"
+            ],
+            [
+                100000,
+                87500,
+                "{$progressBar[0]}{$progressBar[1]}{$progressBar[2]}{$progressBar[3]}{$progressBar[4]}" .
+                "{$progressBar[5]}{$progressBar[6]}{$progressBar[7]}"
+            ],
+            [
+                100000,
+                99999,
+                "{$progressBar[0]}{$progressBar[1]}{$progressBar[2]}{$progressBar[3]}{$progressBar[4]}" .
+                "{$progressBar[5]}{$progressBar[6]}{$progressBar[7]}"
+            ],
+            [100000, 100000, implode($progressBar)]
+        ];
+    }
+
+    /**
+     * @dataProvider getThresholdCases
+     */
+    public function testUploadThresholds($totalSize)
+    {
+        $state = new UploadState([]);
+        $threshold = $state->setProgressThresholds($totalSize);
+
+        $this->assertIsArray($threshold);
+        $this->assertCount(9, $threshold);
+    }
+
+    public function getThresholdCases()
+    {
+        return [
+            [0],
+            [100000],
+            [100001]
+        ];
+    }
+
+    /**
+     * @dataProvider getInvalidIntCases
+     */
+    public function testSetProgressThresholdsThrowsException($totalSize)
+    {
+        $state = new UploadState([]);
+        $this->expectExceptionMessage('The total size of the upload must be a number.');
+        $this->expectException(\InvalidArgumentException::class);
+
+        $state->setProgressThresholds($totalSize);
+    }
+
+    /**
+     * @dataProvider getInvalidIntCases
+     */
+    public function testDisplayProgressThrowsException($totalUploaded)
+    {
+        $state = new UploadState([]);
+        $this->expectExceptionMessage('The size of the bytes being uploaded must be a number.');
+        $this->expectException(\InvalidArgumentException::class);
+
+        $state->displayProgress($totalUploaded);
+    }
+
+    public function getInvalidIntCases()
+    {
+        return [
+            [''],
+            [null],
+            ['aws']
+        ];
+    }
+}

tests/S3/MultipartUploaderTest.php

@@ -316,4 +316,49 @@ public function testAppliesAmbiguousSuccessParsing()
         );
         $uploader->upload();
     }
+
+    public function testFailedUploadPrintsPartialProgressBar()
+    {
+        $partialBar = [ "Transfer initiated...\n|                    | 0.0%\n",
+                        "|==                  | 12.5%\n",
+                        "|=====               | 25.0%\n"];
+        $this->expectOutputString("{$partialBar[0]}{$partialBar[1]}{$partialBar[2]}");
+
+        $this->expectExceptionMessage("An exception occurred while uploading parts to a multipart upload");
+        $this->expectException(\Aws\S3\Exception\S3MultipartUploadException::class);
+        $counter = 0;
+
+        $httpHandler = function ($request, array $options) use (&$counter) {
+            if ($counter < 4) {
+                $body = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><OperationNameResponse><UploadId>baz</UploadId></OperationNameResponse>";
+            } else {
+                $body = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\n\n";
+            }
+            $counter++;
+
+            return Promise\Create::promiseFor(
+                new Psr7\Response(200, [], $body)
+            );
+        };
+
+        $s3 = new S3Client([
+            'version'     => 'latest',
+            'region'      => 'us-east-1',
+            'http_handler' => $httpHandler
+        ]);
+
+        $data = str_repeat('.', 50 * self::MB);
+        $source = Psr7\Utils::streamFor($data);
+
+        $uploader = new MultipartUploader(
+            $s3,
+            $source,
+            [
+                'bucket' => 'test-bucket',
+                'key' => 'test-key',
+                'track_upload' => 'true'
+            ]
+        );
+        $uploader->upload();
+    }
 }