From d9a4a6d227b8062f563a3e9c6b761afc64722865 Mon Sep 17 00:00:00 2001 From: Kevin Moore Date: Fri, 15 Nov 2024 16:08:44 -0800 Subject: [PATCH 1/2] Symlink readme file --- README.md | 107 +----------------------------------------------------- 1 file changed, 1 insertion(+), 106 deletions(-) mode change 100644 => 120000 README.md diff --git a/README.md b/README.md deleted file mode 100644 index ed54c7ad..00000000 --- a/README.md +++ /dev/null @@ -1,106 +0,0 @@ -BREAKING CHANGES IN V2 - -CacheManager v2 introduced some breaking changes when configuring a custom CacheManager. [See the bottom of this page - for the changes.](#breaking-changes-in-v2) - -# flutter_cache_manager - -[![pub package](https://img.shields.io/pub/v/flutter_cache_manager.svg)](https://pub.dartlang.org/packages/flutter_cache_manager) -[![Build Status](https://app.bitrise.io/app/b3454de795b5c22a/status.svg?token=vEfW1ztZ-tkoUx64yXeklg&branch=master)](https://app.bitrise.io/app/b3454de795b5c22a) -[![codecov](https://codecov.io/gh/Baseflow/flutter_cache_manager/branch/master/graph/badge.svg)](https://codecov.io/gh/Baseflow/flutter_cache_manager) - -A CacheManager to download and cache files in the cache directory of the app. Various settings on how long to keep a file can be changed. - -It uses the cache-control http header to efficiently retrieve files. - -The more basic usage is explained here. See the complete docs for more info. - - -## Usage - -The cache manager can be used to get a file on various ways -The easiest way to get a single file is call `.getSingleFile`. - -``` - var file = await DefaultCacheManager().getSingleFile(url); -``` -`getFileStream(url)` returns a stream with the first result being the cached file and later optionally the downloaded file. - -`getFileStream(url, withProgress: true)` when you set withProgress on true, this stream will also emit DownloadProgress when the file is not found in the cache. - -`downloadFile(url)` directly downloads from the web. - -`getFileFromCache` only retrieves from cache and returns no file when the file is not in the cache. - - -`putFile` gives the option to put a new file into the cache without downloading it. - -`removeFile` removes a file from the cache. - -`emptyCache` removes all files from the cache. - -## Other implementations -When your files are stored on Firebase Storage you can use [flutter_cache_manager_firebase](https://pub.dev/packages/flutter_cache_manager_firebase). - -## Customize -The cache manager is customizable by creating a new CacheManager. It is very important to not create more than 1 - CacheManager instance with the same key as these bite each other. In the example down here the manager is created as a - Singleton, but you could also use for example Provider to Provide a CacheManager on the top level of your app. -Below is an example with other settings for the maximum age of files, maximum number of objects -and a custom FileService. The key parameter in the constructor is mandatory, all other variables are optional. - -``` -class CustomCacheManager { - static const key = 'customCacheKey'; - static CacheManager instance = CacheManager( - Config( - key, - stalePeriod: const Duration(days: 7), - maxNrOfCacheObjects: 20, - repo: JsonCacheInfoRepository(databaseName: key), - fileSystem: IOFileSystem(key), - fileService: HttpFileService(), - ), - ); -} -``` -## Frequently Asked Questions -- [How are the cache files stored?](#how-are-the-cache-files-stored) -- [When are the cached files updated?](#when-are-the-cached-files-updated) -- [When are cached files removed?](#when-are-cached-files-removed) - - -### How are the cache files stored? -By default the cached files are stored in the temporary directory of the app. This means the OS can delete the files any time. - -Information about the files is stored in a database using sqflite on Android, iOS and macOs, or in a plain JSON file - on other platforms. The file name of the database is the key of the cacheManager, that's why that has to be unique. - -### When are the cached files updated? -A valid url response should contain a Cache-Control header. More info on the header can be found -[here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control), but in summary it says for how long -the image can be expected to be up to date. It also contains an 'eTag' which can be used to check (after that time) -whether the file did change or if it is actually still valid. - -When a file is in the cache that is always directly returned when calling `getSingleFile` or `getFileStream`. -After that the information is check if the file is actually still valid. If the file is outdated according to the -Cache-Control headers the manager tries to update the file and store the new one in the cache. When you use -`getFileStream` this updated file will also be returned in the stream. - -### When are cached files removed? -The files can be removed by the cache manager or by the operating system. By default the files are stored in a cache - folder, which is sometimes cleaned for example on Android with an app update. - -The cache manager uses 2 variables to determine when to delete a file, the `maxNrOfCacheObjects` and the `stalePeriod`. -The cache knows when files have been used latest. When cleaning the cache (which happens continuously), the cache -deletes files when there are too many, ordered by last use, and when files just haven't been used for longer than -the stale period. - - -## Breaking changes in v2 -- There is no longer a need to extend on BaseCacheManager, you can directly call the constructor. The BaseCacheManager - is therefore renamed to CacheManager as it is not really just a 'base' anymore. - -- The constructor now expects a Config object with some settings you were used to, but some are slightly different. -For example the system where you want to store your files is not just a dictionary anymore, but a FileSystem. That way -you have more freedom on where to store your files. diff --git a/README.md b/README.md new file mode 120000 index 00000000..53a16f37 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +flutter_cache_manager/README.md \ No newline at end of file From a63ce08aa341003fe4e1149fa62ad7540ff1e642 Mon Sep 17 00:00:00 2001 From: Kevin Moore Date: Fri, 15 Nov 2024 16:10:00 -0800 Subject: [PATCH 2/2] Add dart language deets --- flutter_cache_manager/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/flutter_cache_manager/README.md b/flutter_cache_manager/README.md index 8ea4e19e..3c5b77e4 100644 --- a/flutter_cache_manager/README.md +++ b/flutter_cache_manager/README.md @@ -21,8 +21,8 @@ The more basic usage is explained here. See the complete docs for more info. The cache manager can be used to get a file on various ways The easiest way to get a single file is call `.getSingleFile`. -``` - var file = await DefaultCacheManager().getSingleFile(url); +```dart +var file = await DefaultCacheManager().getSingleFile(url); ``` `getFileStream(url)` returns a stream with the first result being the cached file and later optionally the downloaded file. @@ -43,7 +43,7 @@ The easiest way to get a single file is call `.getSingleFile`. If you use the ImageCacheManager mixin on the CacheManager (which is already done on the DefaultCacheManager) you get the following `getImageFile` method for free: -``` +```dart Stream getImageFile(String url, { String key, Map headers, @@ -66,7 +66,7 @@ The cache manager is customizable by creating a new CacheManager. It is very imp Below is an example with other settings for the maximum age of files, maximum number of objects and a custom FileService. The key parameter in the constructor is mandatory, all other variables are optional. -``` +```dart class CustomCacheManager { static const key = 'customCacheKey'; static CacheManager instance = CacheManager(