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

DFImageManager is not just a loader, it's a pipeline that loads images using pluggable components. It features multiple subspecs that integrate things like FLAnimatedImage, AFNetworking, libwebp and more. And it all comes in a strikingly small package with less code than alternative libraries.

1. Getting Started
2. Usage
3. Design
4. Installation
5. Requirements
6. Supported Image Formats
7. Contribution

Features

• Zero config, yet immense customization and flexibility
• Works great with both Objective-C and Swift
• Great performance even on outdated devices, asynchronous and thread safe
• Unit tested

Loading

• Uses NSURLSession with HTTP/2 support
• Has optional AFNetworking integration (which should be your primary choice). Combine the power of both frameworks!
• Uses a single fetch operation for multiple equivalent requests
• Intelligent preheating of images close to the viewport
• 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
• Caching is completely transparent to the client
• Two cache layers, including top level memory cache for decompressed images

Decoding and Processing

• Animated GIF support using best-in-class FLAnimatedImage library
• WebP support
• Progressive image decoding (progressive JPEG and more)
• Background image decompression and scaling in a single step
• Scale large images (~6000x4000 px) and prepare them for display with ease
• Resize and crop loaded images to fit displayed size, add rounded corners or circle

Displaying

• Use UI components and UIKit categories
• Automatically manage requests priorities

Advanced

• Customize different parts of the framework using dependency injection
• Compose image tasks using DFCompositeImageTask. You might use it to show a low-resolution placeholder first and swap to a higher-res one when it is loaded. Or implement custom revalidation policies
• Create custom image managers
• Compose image managers into a tree of responsibility
• Extend DFImageManaging API 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

Usage

Zero Config Image Loading

[[[DFImageManager sharedManager] imageTaskForResource:[NSURL URLWithString:@"http://..."] completion:^(UIImage *image, NSError *error, DFImageResponse *response, DFImageTask *task){
  // Use loaded image
}] resume];

Adding Request Options

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

DFMutableImageRequestOptions *options = [DFMutableImageRequestOptions new]; // builder
options.priority = DFImageRequestPriorityVeryHigh;
options.allowsClipping = YES;

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

[[[DFImageManager sharedManager] imageTaskForRequest:request completion:^(UIImage *image, NSError *error, DFImageResponse *response, DFImageTask *imageTask) {
  // Image is resized and clipped to fill 100x100px square
  if (response.isFastResponse) {
    // Image was returned synchronously from the memory cache
  }
}] resume];

Using Image Task

DFImageTask *imageTask = [[DFImageManager sharedManager] imageTaskForResource:[NSURL URLWithString:@"http://..."] completion:nil];
[imageTask resume];

// Use progress object to track load progress
NSProgress *progress = imageTask.progress;

// Change priority of the already executing task
imageTask.priority = DFImageRequestPriorityHigh;
    
// Cancel image task
[imageTask cancel];

Progressive Image Decoding

// Create image request that allows progressive image
DFMutableImageRequestOptions *options = [DFMutableImageRequestOptions new];
options.allowsProgressiveImage = YES;
DFImageRequest *request = // Create request with given options

DFImageTask *imageTask = .../ Create image task
imageTask.progressiveImageHandler = ^(UIImage *__nonnull image){
  imageView.image = image;
};

[imageTask resume]; // Progressive image should also be enabled by DFImageManager

Preheating Images

NSArray *requestsForAddedItems = ...; // Create image requests
[[DFImageManager sharedManager] startPreheatingImagesForRequests:requestsForAddedItems];
    
NSArray *requestsForRemovedItems = ...; // Create image requests
[[DFImageManager sharedManager] stopPreheatingImagesForRequests:requestsForRemovedItems];

Using 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.managesRequestPriorities = YES; // Automatically changes current request priority when image view gets added/removed from the window

[imageView prepareForReuse];
[imageView setImageWithResource:[NSURL URLWithString:@"http://..."]];

Composing Image Tasks

The DFCompositeImageTask class manages execution of multiple image requests and provides a single completion block.

DFImageTask *previewImageTask = ...; // Create image task for image preview
DFImageTask *fullsizeImageTask = ...; // Create image task for fullsize image

DFCompositeImageTask *compositeImageTask = [[DFCompositeImageTask alloc] initWithImageTasks:@[previewImageTask, fullsizeImageTask] imageHandler:^(UIImage *image, DFImageTask *completedTask, DFCompositeImageTask *compositeTask){
  // One of the image tasks has completed
} completionHandler:^(DFCompositeImageTask *compositeTask){
  // All tasks has either completed or became obsolete
}];
[compositeImageTask resume];

There are many ways how composite requests can be used.

Requesting Image for PHAsset

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
}] resume];

Creating Image Managers

You can either create DFImageManager instance with a custom configuration or even provide your own implementation of DFImageManaging protocol.

// Create dependencies. You can either use existing classes or provide your own.
id<DFImageFetching> fetcher = ...; // Create image fetcher
id<DFImageDecoding> decoder = ...; // Create image decoder
id<DFImageProcessing> processor = ...; // Create image processor
id<DFImageCaching> cache = ...; // Create image cache

// Create configuration to inject dependencies
DFImageManagerConfiguration *configuration = [[DFImageManagerConfiguration alloc] initWithFetcher:fetcher];
configuration.decoder = decoder;
configuration.processor = processor;
configuration.cache = cache;

// Configure progressive image decoding
configuration.allowsProgressiveImage = YES;
configuration.progressiveImageDecodingThreshold = 0.2;

// Create image manager with configuration
DFImageManager *imageManager = [[DFImageManager alloc] initWithConfiguration:configuration];

Composing Image 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. For more info see Composing Image Managers.

id<DFImageManaging> manager = ...; // Create image manager

// 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 Else

DFImageManager is jam-packed with other features. For more info check out the complete documentation and project Wiki

Design

Protocol	Description
DFImageManaging	A high-level API for loading images
DFImageFetching	Performs fetching of image data (NSData)
DFImageDecoding	Converts NSData to UIImage objects
DFImageProcessing	Processes decoded images
DFImageCaching	Stores processed images into memory cache

Installation with CocoaPods

CocoaPods is the dependency manager for Cocoa projects. 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 - DFImageManager core classes
• DFImageManager/UI - UI components
• DFImageManager/NSURLSession - basic networking on top of NSURLSession
• DFImageManager/PhotosKit - Photos Framework support
• DFImageManager/Extensions - extensions that include composite tasks and more

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'

Requirements

iOS 7.0+

Supported Image Formats

• Image formats supported by UIImage (JPEG, PNG, BMP, and more)
• GIF (GIF subspec)
• WebP (WebP subspec)

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.