Progress Tracker for MultipartUploader & MultipartCopy

.changes/nextrelease/feature-progress-tracker.json

@@ -0,0 +1,7 @@
+[
+    {
+        "type": "enhancement",
+        "category": "S3",
+        "description": "'track_upload' configuration option added for MultipartUpload and MultipartCopy"
+    }
+]

src/Multipart/AbstractUploadManager.php

@@ -49,6 +49,9 @@ abstract class AbstractUploadManager implements Promise\PromisorInterface
     /** @var UploadState State used to manage the upload. */
     protected $state;
 
+    /** @var bool Configuration used to indicate if upload progress will be displayed. */
+    protected $displayProgress;
+
     /**
      * @param Client $client
      * @param array  $config
@@ -59,6 +62,12 @@ public function __construct(Client $client, array $config = [])
         $this->info = $this->loadUploadWorkflowInfo();
         $this->config = $config + self::$defaultConfig;
         $this->state = $this->determineState();
+
+        if (isset($config['display_progress'])
+            && is_bool($config['display_progress'])
+        ) {
+            $this->displayProgress = $config['display_progress'];
+        }
     }
 
     /**
@@ -238,7 +247,7 @@ private function determineState(): UploadState
             }
             $id[$param] = $this->config[$key];
         }
-        $state = new UploadState($id);
+        $state = new UploadState($id, $this->config);
         $state->setPartSize($this->determinePartSize());
 
         return $state;

src/Multipart/AbstractUploader.php

@@ -12,6 +12,9 @@ abstract class AbstractUploader extends AbstractUploadManager
     /** @var Stream Source of the data to be uploaded. */
     protected $source;
 
+    /** @var bool Configuration used to indicate if upload progress will be displayed. */
+    protected $displayProgress;
+
     /**
      * @param Client $client
      * @param mixed  $source

src/Multipart/UploadState.php

@@ -13,6 +13,18 @@ class UploadState
     const INITIATED = 1;
     const COMPLETED = 2;
 
+    private $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,12 +37,24 @@ class UploadState
     /** @var int Identifies the status the upload. */
     private $status = self::CREATED;
 
+    /** @var array Thresholds for progress of the upload. */
+    private $progressThresholds = [];
+
+    /** @var boolean Determines status for tracking the upload */
+    private $displayProgress = false;
+
     /**
      * @param array $id Params used to identity the upload.
      */
-    public function __construct(array $id)
+    public function __construct(array $id, array $config = [])
     {
         $this->id = $id;
+
+        if (isset($config['display_progress'])
+            && is_bool($config['display_progress'])
+        ) {
+            $this->displayProgress = $config['display_progress'];
+        }
     }
 
     /**
@@ -45,7 +69,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 +100,52 @@ 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): array
+    {
+        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 getDisplayProgress($totalUploaded): void
+    {
+        if (!is_numeric($totalUploaded)) {
+            throw new \InvalidArgumentException(
+                'The size of the bytes being uploaded must be a number.'
+            );
+        }
+
+        if ($this->displayProgress) {
+            while (!empty($this->progressBar)
+                && $totalUploaded >= $this->progressThresholds[0]
+            ) {
+                echo array_shift($this->progressBar);
+                array_shift($this->progressThresholds);
+            }
+        }
+    }
+
     /**
      * Marks a part as being uploaded.
      *
@@ -108,7 +178,6 @@ public function hasPartBeenUploaded($partNumber)
     public function getUploadedParts()
     {
         ksort($this->uploadedParts);
-
         return $this->uploadedParts;
     }
 

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.
+     * - display_progress: (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 ($this->displayProgress) {
+            $this->getState()->setProgressThresholds(
+                $this->sourceMetadata["ContentLength"]
+            );
+        }
     }
 
     /**
@@ -238,5 +246,4 @@ private function getInputSource($inputSource)
         $sourceBuilder .= ltrim(rawurldecode($inputSource), '/');
         return $sourceBuilder;
     }
-
 }

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 ($this->displayProgress) {
+            $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.
@@ -59,6 +61,13 @@ protected function handleResult(CommandInterface $command, ResultInterface $resu
             $partData[$checksumMemberName] = $result[$checksumMemberName];
         }
         $this->getState()->markPartAsUploaded($command['PartNumber'], $partData);
+
+        // Updates counter for uploaded bytes.
+        $this->uploadedBytes += $command["ContentLength"];
+        // Sends uploaded bytes to progress tracker if getDisplayProgress set
+        if ($this->displayProgress) {
+            $this->getState()->getDisplayProgress($this->uploadedBytes);
+        }
     }
 
     abstract protected function extractETag(ResultInterface $result);