[path_provider] Add getApplicationCachePath() (#4483)

Provides a suitable place for caching application-specific files on all supported platforms.

| Platform | Location |
|---|---|
| Android | `<app>/cache` |
| iOS | `<app>/Library/Caches` |
| Linux | `$XDG_CACHE_HOME/<app>` or `~/.cache/<app>` |
| macOS | `~/Library/Caches/<app>` or `~/Library/Containers/<app>/Data/Library/Caches/<app>` |
| Windows | `%LOCALAPPDATA%/<app>` |

Fixes: flutter/flutter#105386

packages/path_provider/path_provider/CHANGELOG.md

@@ -1,5 +1,6 @@
-## NEXT
+## 2.1.0
 
+* Adds getApplicationCachePath() for storing app-specific cache files.
 * Updates minimum supported macOS version to 10.14.
 * Updates minimum supported SDK version to Flutter 3.3/Dart 2.18.
 

packages/path_provider/path_provider/README.md

@@ -35,6 +35,7 @@ Directories support by platform:
 | Application Support | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
 | Application Library | ❌️ | ✔️ | ❌️ | ✔️ | ❌️ |
 | Application Documents | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
+| Application Cache | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
 | External Storage | ✔️ | ❌ | ❌ | ❌️ | ❌️ |
 | External Cache Directories | ✔️ | ❌ | ❌ | ❌️ | ❌️ |
 | External Storage Directories | ✔️ | ❌ | ❌ | ❌️ | ❌️ |

packages/path_provider/path_provider/example/integration_test/path_provider_test.dart

@@ -25,6 +25,11 @@ void main() {
     _verifySampleFile(result, 'applicationSupport');
   });
 
+  testWidgets('getApplicationCacheDirectory', (WidgetTester tester) async {
+    final Directory result = await getApplicationCacheDirectory();
+    _verifySampleFile(result, 'applicationCache');
+  });
+
   testWidgets('getLibraryDirectory', (WidgetTester tester) async {
     if (Platform.isIOS) {
       final Directory result = await getLibraryDirectory();

packages/path_provider/path_provider/example/lib/main.dart

@@ -41,6 +41,7 @@ class _MyHomePageState extends State<MyHomePage> {
   Future<Directory?>? _appSupportDirectory;
   Future<Directory?>? _appLibraryDirectory;
   Future<Directory?>? _appDocumentsDirectory;
+  Future<Directory?>? _appCacheDirectory;
   Future<Directory?>? _externalDocumentsDirectory;
   Future<List<Directory>?>? _externalStorageDirectories;
   Future<List<Directory>?>? _externalCacheDirectories;
@@ -102,6 +103,12 @@ class _MyHomePageState extends State<MyHomePage> {
     });
   }
 
+  void _requestAppCacheDirectory() {
+    setState(() {
+      _appCacheDirectory = getApplicationCacheDirectory();
+    });
+  }
+
   void _requestExternalStorageDirectory() {
     setState(() {
       _externalDocumentsDirectory = getExternalStorageDirectory();
@@ -206,6 +213,23 @@ class _MyHomePageState extends State<MyHomePage> {
                 ),
               ],
             ),
+            Column(
+              children: <Widget>[
+                Padding(
+                  padding: const EdgeInsets.all(16.0),
+                  child: ElevatedButton(
+                    onPressed: _requestAppCacheDirectory,
+                    child: const Text(
+                      'Get Application Cache Directory',
+                    ),
+                  ),
+                ),
+                FutureBuilder<Directory?>(
+                  future: _appCacheDirectory,
+                  builder: _buildDirectory,
+                ),
+              ],
+            ),
             Column(
               children: <Widget>[
                 Padding(

packages/path_provider/path_provider/example/pubspec.yaml

@@ -16,7 +16,7 @@ dependencies:
     # The example app is bundled with the plugin so we use a path dependency on
     # the parent directory to use the current plugin's version.
     path: ../
-  path_provider_platform_interface: ^2.0.0
+  path_provider_platform_interface: ^2.1.0
 
 dev_dependencies:
   build_runner: ^2.1.10

packages/path_provider/path_provider/lib/path_provider.dart

@@ -107,8 +107,9 @@ Future<Directory> getLibraryDirectory() async {
 /// Path to a directory where the application may place data that is
 /// user-generated, or that cannot otherwise be recreated by your application.
 ///
-/// Consider using another path, such as [getApplicationSupportDirectory] or
+/// Consider using another path, such as [getApplicationSupportDirectory],
-/// [getExternalStorageDirectory], if the data is not user-generated.
+/// [getApplicationCacheDirectory], or [getExternalStorageDirectory], if the
+/// data is not user-generated.
 ///
 /// Example implementations:
 /// - `NSDocumentDirectory` on iOS and macOS.
@@ -125,6 +126,22 @@ Future<Directory> getApplicationDocumentsDirectory() async {
   return Directory(path);
 }
 
+/// Path to a directory where the application may place application-specific
+/// cache files.
+///
+/// If this directory does not exist, it is created automatically.
+///
+/// Throws a [MissingPlatformDirectoryException] if the system is unable to
+/// provide the directory.
+Future<Directory> getApplicationCacheDirectory() async {
+  final String? path = await _platform.getApplicationCachePath();
+  if (path == null) {
+    throw MissingPlatformDirectoryException(
+        'Unable to get application cache directory');
+  }
+  return Directory(path);
+}
+
 /// Path to a directory where the application may access top level storage.
 ///
 /// Example implementation:

packages/path_provider/path_provider/pubspec.yaml

@@ -2,7 +2,7 @@ name: path_provider
 description: Flutter plugin for getting commonly used locations on host platform file systems, such as the temp and app data directories.
 repository: https://github.com/flutter/packages/tree/main/packages/path_provider/path_provider
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+path_provider%22
-version: 2.0.15
+version: 2.1.0
 
 environment:
   sdk: ">=2.18.0 <4.0.0"
@@ -25,11 +25,11 @@ flutter:
 dependencies:
   flutter:
     sdk: flutter
-  path_provider_android: ^2.0.6
+  path_provider_android: ^2.1.0
-  path_provider_foundation: ^2.1.0
+  path_provider_foundation: ^2.3.0
-  path_provider_linux: ^2.0.1
+  path_provider_linux: ^2.2.0
-  path_provider_platform_interface: ^2.0.0
+  path_provider_platform_interface: ^2.1.0
-  path_provider_windows: ^2.0.2
+  path_provider_windows: ^2.2.0
 
 dev_dependencies:
   flutter_test: