Kingfisher: A Swift repository from xylinuxkernel

Kingfisher is a lightweight and pure Swift implemented library for downloading and caching image from the web. This project is heavily inspired by the popular SDWebImage. And it provides you a chance to use pure Swift alternative in your next app.

Features

Everything in Kingfisher is asynchronous, not only downloading, but also caching. That means you never need to worry about blocking your UI thread.
Multiple-layer cache. Downloaded images will be cached in both memory and disk. So there is no need to download again, this could boost your app's perceptual speed dramatically.
Cache management. You can set the max duration or size the cache takes. From this, the cache will be cleaned automatically to prevent taking too many resources.
Modern framework. Kingfisher uses NSURLSession and the latest technology of GCD, which makes it a strong and swift framework. It also provides you easy APIs to use.
Cancelable processing task. You can cancel the downloading process if it is not needed anymore.
Prefetching. You can prefetch and cache the images which might soon appear in the page. It will bring your users great experience.
Independent components. You can use the downloader or caching system separately. Or even create your own cache based on Kingfisher's code.
Options to decompress the image in background before rendering it, which could improve the UI performance.
Categories over UIImageView, NSImage and UIButton for setting image from a URL directly. Use the same code across all Apple platforms.
Support GIF seamlessly. You could just download and set your GIF images as the same as you do for PNG/JPEG format using AnimatedImageView.
You could set Activity Indicator for your UIImageView or NSImageView to enable the indicator during loading image from web.

Requirements

iOS 8.0+, tvOS 9.0+, watchOS 2.0+ or OS X 10.10+
Xcode 7.3 or above

If you are upgrading to Kingfisher 2.x from 1.x, please read the Kingfisher 2.0 Migration Guide for more information.

Kingfisher is now supporting Swift 2.2. If you need to use Kingfisher in Swift 2.1, you need to pin the version to 2.1.0.

Swift 3

Kingfisher is now supporting Swift 3 in the swift3 branch. It is now under development and not be officially released yet. You could specify to that branch if you are working in a Swift 3 project. However, please reconsider if you want to use it in a releasing orientation product, since more breaking change would be applied later.

Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

$ gem install cocoapods

To integrate Kingfisher into your Xcode project using CocoaPods, specify it in your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!

pod 'Kingfisher', '~> 2.4'

If your CocoaPods Version > 1.0.0, you needs add Target name like this:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!

target ‘<Your Target Name>’ do
    pod 'Kingfisher', '~> 2.4'
end

Then, run the following command:

$ pod install

You should open the {Project}.xcworkspace instead of the {Project}.xcodeproj after you installed anything from CocoaPods.

For more information about how to use CocoaPods, I suggest this tutorial.

Carthage

Carthage is a decentralized dependency manager for Cocoa application. To install the carthage tool, you can use Homebrew.

$ brew update
$ brew install carthage

To integrate Kingfisher into your Xcode project using Carthage, specify it in your Cartfile:

github "onevcat/Kingfisher" ~> 2.4

Then, run the following command to build the Kingfisher framework:

$ carthage update

At last, you need to set up your Xcode project manually to add the Kingfisher framework.

On your application targets’ “General” settings tab, in the “Linked Frameworks and Libraries” section, drag and drop each framework you want to use from the Carthage/Build folder on disk.

On your application targets’ “Build Phases” settings tab, click the “+” icon and choose “New Run Script Phase”. Create a Run Script with the following content:

/usr/local/bin/carthage copy-frameworks

and add the paths to the frameworks you want to use under “Input Files”:

$(SRCROOT)/Carthage/Build/iOS/Kingfisher.framework

For more information about how to use Carthage, please see its project page.

Manually

It is not recommended to install the framework manually, but if you prefer not to use either of the aforementioned dependency managers, you can integrate Kingfisher into your project manually. A regular way to use Kingfisher in your project would be using Embedded Framework.

Add Kingfisher as a submodule. In your favorite terminal, cd into your top-level project directory, and entering the following command:

$ git submodule add https://github.com/onevcat/Kingfisher.git

Open the Kingfisher folder, and drag Kingfisher.xcodeproj into the file navigator of your app project, under your app project.
In Xcode, navigate to the target configuration window by clicking on the blue project icon, and selecting the application target under the "Targets" heading in the sidebar.
In the tab bar at the top of that window, open the "Build Phases" panel.
Expand the "Target Dependencies" group, and add Kingfisher.framework.
Click on the + button at the top left of "Build Phases" panel and select "New Copy Files Phase". Rename this new phase to "Copy Frameworks", set the "Destination" to "Frameworks", and add Kingfisher.framework of the platform you need.

Usage

You can find the full API documentation at CocoaDocs.

UIImageView and NSImageView category

Use Kingfisher in your project is as easy as a pie. You can use the UIImageView or NSImageView category and trust Kingfisher to manage downloading and cache images.

Basic

In your source files, add the following code:

import Kingfisher

imageView.kf_setImageWithURL(NSURL(string: "http://your_image_url.png")!)

In most cases, Kingfisher is used in a reusable cell. Since the downloading process is asynchronous, the earlier image will be remained during the downloading of newer one. The placeholder version of this API could help:

imageView.kf_setImageWithURL(NSURL(string: "http://your_image_url.png")!, placeholderImage: nil)

By default, Kingfisher will use absoluteString of the URL as the key for cache. If you need another key instead of URL's absoluteString, there is another set of APIs accepting Resource as parameter:

let URL = NSURL(string: "http://your_image_url.png")!
let resource = Resource(downloadURL: URL, cacheKey: "your_customized_key")

imageView.kf_setImageWithResource(resource)

It will ask Kingfisher's manager to get the image for the "your_customized_key" from memory and disk first. If the manager does not find it, it will try to download the image at the URL, and store it with cacheKey ("your_customized_key" here) for next use.

Options

Kingfisher will search in cache (both memory and disk) first with the URL, if no image found, it will try to download and store the image in the cache. You can change this behavior by passing an option, to let it ignore the cache.

imageView.kf_setImageWithURL(NSURL(string: "your_image_url")!,
                         placeholderImage: nil,
                              optionsInfo: [.ForceRefresh])

There are also other options to control the cache level, downloading priority, etc. Take some other examples:

If you need to cache the downloaded image to a customized cache instead of the default one:

let myCache = ImageCache(name: "my_cache")

imageView.kf_setImageWithURL(NSURL(string: "your_image_url")!,
                         placeholderImage: nil,
                              optionsInfo: [.TargetCache(myCache)])

This is useful if you want to use a specified cache for some reasons.

And if you need to fade in the image to image view during 1 second (image transition only works for iOS platform now):

imageView.kf_setImageWithURL(NSURL(string: "your_image_url")!,
                         placeholderImage: nil,
                              optionsInfo: [.Transition(ImageTransition.Fade(1))])

You are also free to combine these options to customize the behavior:

let queue = dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0)
let optionInfo: KingfisherOptionsInfo = [
    .ForceRefresh,
    .DownloadPriority(0.5),
    .CallbackDispatchQueue(queue),
    .Transition(ImageTransition.Fade(1))
]

For more information about options, please see the KingfisherOptionsInfo in the documentation.

Callbacks

You can get a chance during Kingfisher downloading images and when the process is done:

imageView.kf_setImageWithURL(NSURL(string: "your_image_url")!,
                         placeholderImage: nil,
                              optionsInfo: nil,
                            progressBlock: { (receivedSize, totalSize) -> () in
                                print("Download Progress: \(receivedSize)/\(totalSize)")
                            },
                        completionHandler: { (image, error, cacheType, imageURL) -> () in
                            print("Downloaded and set!")
                        }
)

Cancel Task

You can cancel the task if the images are not needed anymore. It could be useful when you use Kingfisher to set an image in a cell of table view or collection view, but users scroll the view and the cells disappeared before downloading finishing.

imageView.kf_setImageWithURL(NSURL(string: "http://your_image_url.png")!)

// The image retrieving will stop.
imageView.kf_cancelDownloadTask()

If you need more control and want to do some check before cancelling, all kf_setImageWithURL methods return a RetrieveImageTask object as well. You can also hold and manage it, then call cancel on the task:

let task = imageView.kf_setImageWithURL(NSURL(string: "http://your_image_url.png")!)

let urlShouldNotBeCancelled: URL = ...

if task.downloadTask?.URL != urlShouldNotBeCancelled {
    task.cancel()
}

Downloader & Cache system

Kingfisher will use the default downloader and cache if you do not specify them by yourself. You can access them by using KingfisherManager.sharedManager.downloader and KingfisherManager.sharedManager.cache. You can adjust some parameters to meet your demands:

let downloader = KingfisherManager.sharedManager.downloader

// Download process will timeout after 5 seconds. Default is 15.
downloader.downloadTimeout = 5

// requestModifier will be called before image download request made.
downloader.requestModifier = {
    (request: NSMutableURLRequest) in
    // Do what you need to modify the download request. Maybe add your HTTP basic authentication for example.
}

// Hosts in trustedHosts will be ignore the received challenge.
// You can add the host of your self-signed site to it to bypass the SSL.
// (Do not do it unless you know what you are doing)
downloader.trustedHosts = Set(["your_self_signed_host"])

let cache = KingfisherManager.sharedManager.cache

// Set max disk cache to 50 mb. Default is no limit.
cache.maxDiskCacheSize = 50 * 1024 * 1024

// Set max disk cache to duration to 3 days, Default is 1 week.
cache.maxCachePeriodInSecond = 60 * 60 * 24 * 3

// Get the disk size taken by the cache.
cache.calculateDiskCacheSizeWithCompletionHandler { (size) -> () in
    print("disk size in bytes: \(size)")
}

The memory cache will be purged whenever the app switched to background or receiving a memory warning. Disk cache will be cleaned when the conditions are met. You can also clear these caches manually:

// Clear memory cache right away.
cache.clearMemoryCache()

// Clear disk cache. This is an async operation.
cache.clearDiskCache()

// Clean expired or size exceeded disk cache. This is an async operation.
cache.cleanExpiredDiskCache()

Prefetching

You could prefetch some images and cache them before you display them on the screen. This is useful when you know a list of image resources you know they would probably be shown later. Since the prefetched images are already in the cache system, there is no need to request them again when you really need to display them in a image view. It will boost your UI and bring your users great experience.

To prefetch some images, you could use the ImagePrefetcher:

let urls = ["http://example.com/image1.jpg", "http://example.com/image2.jpg"].map { NSURL(string: $0)! }
let prefetcher = ImagePrefetcher(urls: urls, optionsInfo: nil, progressBlock: nil, completionHandler: {
    (skippedResources, failedResources, completedResources) -> () in
    print("These resources are prefetched: \(completedResources)")
})
prefetcher.start()

You can also stop a prefetch whenever you need:

prefetcher.stop()

After prefetching, you could retrieve image or set the image view with other Kingfisher's methods, with the same ImageCache object you used for the prefetching.

Animated GIF

You can load animated GIF by replacing UIImageView with AnimatedImageView, and then using the same API for a regular image view like this:

let imageView = AnimatedImageView()
imageView.kf_setImageWithURL(NSURL(string: "your_animated_gif_image_url")!)

AnimatedImageView will only decode some frames of your GIF image to get a smaller memory footprint. You can set the frame count you need to pre-load by setting the framePreloadCount property of an AnimatedImageView (default is 10).

You can also load a GIF file by a regular UIImageView. However, all frames will be loaded and decoded into memory. It is probably not suitable if you are loading a large GIF image. For most cases, you may want to use AnimatedImageView. The GIF support in Kingfisher's UIImageView only fits the small files, and now is mostly serving for back compatibility.

Future of Kingfisher

I want to keep Kingfisher slim. This framework will focus on providing a simple solution for image downloading and caching. But that does not mean the framework will not be improved. Kingfisher is far away from perfect, and necessary and useful features will be added later to make it better.

About the logo

The logo of Kingfisher is inspired by Tangram (七巧板), a dissection puzzle consisting of seven flat shapes from China. I believe she's a kingfisher bird instead of a swift, but someone insists that she is a pigeon. I guess I should give her a name. Hi, guys, do you have any suggestion?

Contact

Follow and contact me on Twitter or Sina Weibo. If you find an issue, just open a ticket on it. Pull requests are warmly welcome as well.

License

Kingfisher is released under the MIT license. See LICENSE for details.

xylinuxkernel/Kingfisher