DFImageManager

Advanced iOS framework for loading, caching, processing, displaying and preheating images. It uses latest features in iOS SDK and doesn't reinvent existing technologies. It provides a powerful API that will extend the capabilities of your app.

The DFImageManager is not just a loader, it is a pipeline for executing image requests using pluggable components. It features multiple subspecs that automatically integrate things like AFNetworking, FLAnimatedImage as a performant animated GIF engine, and more.

Features

• Zero config, yet immense customization and extensibility
• Works great with Swift
• Common APIs for different resources (NSURL, PHAsset, ALAsset, and your custom classes)
• Great performance even on outdated devices, asynchronous and thread safe
• Unit tested

Loading

• Uses latest advancements in Foundation URL Loading System including NSURLSession that supports HTTP/2
• Has basic built-in networking implementation, and optional AFNetworking integration (which should be your primary choice). Combine the power of both frameworks!
• Groups similar requests and never executes them twice
• Progress tracking using NSProgress

Caching

• Instead of reinventing a caching methodology it relies on HTTP cache as defined in HTTP specification and caching implementation provided by Foundation URL Loading System. The caching and revalidation are completely transparent to the client
• Two levels of cache, including top level memory cache for decompressed and processed images

Decoding and Processing

• Animated GIF support using best-in-class FLAnimatedImage library
• WebP support
• Background image decompression
• Resize and crop loaded images, add rounded corners or circle

Displaying

• Use UI components and UIKit categories
• Automatically retry load if the network load failes

Advanced

• Intelligent preheating of images that are close to the viewport
• Use DFCompositeImageTask to execute and handle multiple image requests. You might show a low-resolution placeholder first and swap to a higher-res one when it is loaded. Or implement some custom revalidation policies
• Customize different parts of the framework using dependency injection
• Add support for custom image requests by composing image managers into a tree of responsibility
• Add support for custom image requests using DFProxyImageManager

Getting Started

• Download the latest release version
• Take a look at the comprehensive demo, it's easy to install with pod try DFImageManager command
• Check out the complete documentation
• View the growing project Wiki and FAQ
• Experiment with the APIs in a Swift playground available in the project
• Install using CocoaPods, import <DFImageManager/DFImageManagerKit.h> and enjoy!
• Check out Nuke - experimental Swift framework with similar functionality

Requirements

iOS 7.0+

Usage

Zero config image fetching

DFImageTask *task = [[DFImageManager sharedManager] imageTaskForResource:[NSURL URLWithString:@"http://..."] completion:^(UIImage *image, NSDictionary *info) {
  // Use decompressed image and inspect info
}];
[task resume];

[task cancel]; // task can be used to cancel the request

Add request options

NSURL *imageURL = [NSURL URLWithString:@"http://..."];

DFMutableImageRequestOptions *options = [DFMutableImageRequestOptions new]; // builder
options.allowsClipping = YES;
options.userInfo = @{ DFURLRequestCachePolicyKey : @(NSURLRequestReturnCacheDataDontLoad) };

DFImageRequest *request = [DFImageRequest requestWithResource:imageURL targetSize:CGSizeMake(100.f, 100.f) contentMode:DFImageContentModeAspectFill options:options.options];

[[[DFImageManager sharedManager] imageTaskForRequest:request completion:^(UIImage *image, NSDictionary *info) {
// Image is resized and clipped to fill 100x100px square
}] resume];

Use UI components

Use methods from UIImageView category for simple cases:

UIImageView *imageView = ...;
[imageView df_setImageWithResource:[NSURL URLWithString:@"http://..."]];

Use DFImageView for more advanced features:

DFImageView *imageView = ...;
imageView.allowsAnimations = YES; // Animates images when the response isn't fast enough
imageView.allowsAutoRetries = YES; // Retries when network reachability changes

[imageView prepareForReuse];
[imageView setImageWithResource:[NSURL URLWithString:@"http://..."]];
// Or use other APIs, for example, set multiple requests [imageView setImageWithRequests:@[ ... ]];

Start multiple requests with a single completion handler

The DFCompositeImageTask class manages execution of one or many image requests. It also stores execution state for each request.

DFImageRequest *previewRequest = [DFImageRequest requestWithResource:[NSURL URLWithString:@"http://preview"]];
DFImageRequest *fullsizeRequest = [DFImageRequest requestWithResource:[NSURL URLWithString:@"http://fullsize_image"]];

NSArray *requests = @[ previewRequest, fullsizeRequest ];
DFCompositeImageTask *task = [DFCompositeImageTask requestImageForRequests:requests imageHandler:^(UIImage *image, NSDictionary *info, DFImageRequest *request) {
  // Handler is called at least once
  // For more info see DFCompositeImageTask class
} completionHandler:nil];

There are many ways how composite requests can be used.

Use the same DFImageManaging API for PHAsset, ALAsset and your custom classes

PHAsset *asset = ...;
DFImageRequest *request = [DFImageRequest requestWithResource:asset targetSize:CGSizeMake(100.f, 100.f) contentMode:DFImageContentModeAspectFill options:nil];
[[[DFImageManager sharedManager] imageTaskForRequest:request completion:^(UIImage *image, NSDictionary *info) {
  // Image resized to 100x100px square
  // Photos Kit image manager does most of the hard work
}] resume];

Use composite managers

The DFCompositeImageManager allows clients to construct a tree of responsibility from multiple image managers, where image requests are dynamically dispatched between them. Each manager should conform to DFImageManaging protocol. The DFCompositeImageManager also conforms to DFImageManaging protocol, which lets clients treat individual objects and compositions uniformly. The default [DFImageManager sharedManager] is a composite that contains all built in managers: the ones that support NSURL fetching, PHAsset objects, etc.

It's easy for clients to add additional managers to the shared manager. You can either add support for new image requests, or intercept existing ones. For more info see Composing Image Managers.

// Implement custom image fetcher that conforms to DFImageFetching protocol,
// including - (BOOL)canHandleRequest:(DFImageRequest *)request; method
id<DFImageFetching> fetcher = [YourImageFetcher new];
id<DFImageProcessing> processor = [YourImageProcessor new];
id<DFImageCaching> cache = [YourImageMemCache new];

// Create DFImageManager with your configuration.
DFImageManagerConfiguration *configuration = [DFImageManagerConfiguration configurationWithFetcher:fetcher processor:processor cache:cache];
id<DFImageManaging> manager = [[DFImageManager alloc] initWithConfiguration:configuration];

// Create composite manager with your custom manager and all built-in managers.
NSArray *managers = @[ manager, [DFImageManager sharedManager] ];
id<DFImageManaging> compositeImageManager = [[DFCompositeImageManager alloc] initWithImageManagers:managers];

// Use dependency injector to set shared manager
[DFImageManager setSharedManager:compositeImageManager];

What's more

Those were the most common cases. DFImageManager is packed with other features. For more info check out the complete documentation and project Wiki

Supported Resources

• NSURL with http, https, ftp, file, and data schemes (AFNetworking or NSURLSession subspec)
• PHAsset, NSURL with com.github.kean.photos-kit scheme (PhotosKit subspec)
• DFALAsset, ALAsset, NSURL with assets-library scheme (AssetsLibrary subspec)

Supported Image Formats

• Everything supported by UIImage (jpg, png, bmp, and more)
• gif (GIF subspec)
• webp (WebP subspec)

Installation with CocoaPods

CocoaPods is the dependency manager for Cocoa projects, which automates the process of integrating third-party frameworks like DFImageManager. If you are not familiar with CocoaPods the best place to start would be official CocoaPods guides. To install DFImageManager add a dependency in your Podfile:

# Podfile
platform :ios, '7.0'
pod 'DFImageManager'

By default it will install subspecs:

• DFImageManager/Core - core DFImageManager classes
• DFImageManager/UI - UI components
• DFImageManager/NSURLSession - basic networking on top of NSURLSession
• DFImageManager/PhotosKit - Photos Framework support
• DFImageManager/AssetsLibrary - ALAssetsLibrary support

There are three more optional subspecs:

• DFImageManager/AFNetworking - replaces networking stack with AFNetworking
• DFImageManager/GIF - GIF support with a FLAnimatedImage dependency
• DFImageManager/WebP - WebP support with a libwebp dependency

To install optional dependencies include them in your Podfile:

# Podfile
platform :ios, '7.0'
pod 'DFImageManager'
pod 'DFImageManager/AFNetworking'
pod 'DFImageManager/GIF'
pod 'DFImageManager/WebP'

Contribution

• If you need help, use Stack Overflow. (Tag 'dfimagemanager')
• If you'd like to ask a general question, use Stack Overflow.
• If you found a bug, and can provide steps to reproduce it, open an issue.
• If you have a feature request, open an issue.
• If you want to contribute, branch of the develop branch and submit a pull request.

Contacts

License

DFImageManager is available under the MIT license. See the LICENSE file for more info.