Media: large file upload

migrations/54-60/new-features.md

@@ -11,3 +11,50 @@ sidebar_position: 1
 All the new features that have been added to this version.
 Any changes in best practice.
 
+## Filesystem adapter
+
+### Improving large files handling
+
+Starting from 6.0 Media manager introduces new class `TmpFileUpload` that represent temporary file, 
+which is a reference to temporary file (that was just uploaded), without keeping whole file in the memory. 
+This allows to upload large files without violation PHP max_memory limits.
+
+Note: Media API calls still handle base64 encoded images, which still uses PHP memory directly.
+
+It is recommended to update existing Filesystem Adapter:
+```php
+// Before:
+public function createFile(string $name, string $path, $data): string
+{
+    ...
+    File::write($dstPath, $data);
+    ...
+}
+
+// After:
+public function createFile(string $name, string $path, $data): string
+{
+    ...
+    if ($data instanceof TmpFileUpload) {
+        File::upload($data->getUri(), $dstPath);
+    } else {
+        File::write($dstPath, $data);
+    }    
+    ...
+}
+
+// Or:
+public function createFile(string $name, string $path, $data): string
+{
+    ...
+    if ($data instanceof TmpFileUpload) {
+        $data = fopen($data->getUri(), 'r');
+    }
+
+    File::write($dstPath, $data);
+    ...
+}
+```
+The same for `updateFile()` method.
+
+PR: https://github.com/joomla/joomla-cms/pull/44848