Add more comments

src/Api/Upload.php

@@ -42,27 +42,27 @@ public static function chunk(
 		string $source,
 		string $filename
 	): string|null {
-		// if the file is uploaded in chunks
+		// if the file is uploaded in chunks…
 		if ($total = (int)$api->requestHeaders('Upload-Length')) {
 			// ensure the tmp upload directory exists
 			Dir::make($dir = static::tmp());
 
-			// get id of file upload and ensure it doesn't
-			// contain forbidden characters
+			// get id for file upload and
+			// strip it from forbidden characters
 			$id = $api->requestHeaders('Upload-Id');
 			$id = Str::slug($id, '', 'a-z0-9');
 
 			// create path for file in tmp upload directory;
-			// append id while the file isn't completely uploaded yet
+			// prefix with id while file isn't completely uploaded yet
 			$filename  = basename($filename);
 			$tmp       = $dir . '/' . $filename;
 			$tmpWithId = $dir . '/' . $id . '-' . $filename;
 
-			// get byte offset for current chunk and compare it
-			// against existing partial file to validate the request
+			// get byte offset of current chunk for total file length
 			$offset = (int)$api->requestHeaders('Upload-Offset');
 
-			// validate chunk request
+			// validate various aspects of the request
+			// to ensure the chunk isn't try to do malicious actions
 			static::validateChunk(
 				source:   $source,
 				tmp:      $tmpWithId,
@@ -81,7 +81,7 @@ public static function chunk(
 			// really returns the updated file size
 			clearstatcache();
 
-			// if partial file isn't complete yet, return early
+			// if file isn't complete yet, return early
 			if (F::size($tmpWithId) < $total) {
 				return null;
 			}
@@ -107,7 +107,7 @@ public static function chunkSize(): int
 			Str::toBytes(ini_get('post_max_size'))
 		];
 
-		// if server is behind a cloudflare proxy
+		// consider cloudflare proxy limit, if detected
 		if (isset($_SERVER['HTTP_CF_CONNECTING_IP']) === true) {
 			$max[] = Str::toBytes('100M');
 		}
@@ -129,6 +129,7 @@ public static function clean(): void
 			}
 		}
 
+		// remove tmp directory if completely empty
 		if (Dir::isEmpty($dir) === true) {
 			Dir::remove($dir);
 		}
@@ -182,17 +183,22 @@ protected static function validateChunk(
 		}
 
 		if (F::exists($tmp) === true) {
+			// sent chunk is expected to be the first part,
+			// but tmp file already exists
 			if ($offset === 0) {
 				throw new DuplicateException('A tmp file upload with the same filename and upload id already exists: ' . $name);
 			}
 
+			// sent chunk's offset is not the continuation of the tmp file
 			if ($offset !== F::size($tmp)) {
 				throw new Exception('Chunk offset ' . $offset . ' does not match the existing tmp upload file size of ' . F::size($tmp));
 			}
 		} elseif ($offset > 0) {
+			// sent chunk is not expected to be the first part,
+			// but no tmp file to continue exists yet
 			throw new NotFoundException('Chunk offset ' . $offset . ' for non-existing tmp file: ' . $name);
 		} elseif ($offset === 0) {
-			// validate file for first chunk;
+			// validate file (extension, name) for first chunk;
 			// will also be validate again by `$model->createFile()`
 			// when completely uploaded
 			FileRules::validFile($file, false);