Advanced framework for loading, caching, processing, displaying and preheating images. It uses latest advancements in iOS SDK and doesn't reinvent existing technologies.

DFImageManager is a pipeline that loads images using multiple dependencies which can be injected in runtime. It features multiple subspecs that integrate things like FLAnimatedImage, libwebp, and more.

Programming in Swift? Try Nuke.

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

Features

• Zero config
• Works great with both Objective-C and Swift
• Performant, asynchronous, thread safe
• Comprehensive unit test coverage

Loading

• Uses NSURLSession with HTTP/2 support
• Has optional AFNetworking integration, combine the power of both frameworks!
• Uses a single fetch operation for multiple equivalent requests
• Intelligent preheating of images close to the viewport

Caching

• Doesn't reinvent caching, relies on HTTP cache and its implementation in 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 (including progressive JPEG)
• Background image decompression and scaling in a single step
• Resize and crop loaded images to fit displayed size, add rounded corners or circle

Advanced

• Customize different parts of the framework using dependency injection
• Create custom image managers
• Compose image managers into a tree of responsibility

Getting Started

• Take a look at comprehensive demo, it's easy to install with pod try DFImageManager command
• Check out complete documentation and Wiki
• Install using CocoaPods, @import DFImageManager and enjoy!

Usage

Zero Config

[[DFImageManager 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 = DFImageRequestPriorityHigh;
options.allowsClipping = YES;

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

[[DFImageManager 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 *task = [DFImageManager imageTaskForResource:[NSURL URLWithString:@"http://..."] completion:nil];
[task resume];

NSProgress *progress = task.progress; // Track progress
task.priority = DFImageRequestPriorityHigh; // Change priority of executing task
[task cancel]; // Cancel image task

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://..."]];

UICollectionView

- (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath {
    UICollectionViewCell *cell = <#cell#>
    DFImageView *imageView = (id)[cell viewWithTag:15];
    if (!imageView) {
        imageView = [[DFImageView alloc] initWithFrame:cell.bounds];
        imageView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
        imageView.tag = 15;
        [cell addSubview:imageView];
    }
    [imageView prepareForReuse];
    [imageView setImageWithResource:<#image_url#>];
    return cell;
}

Cancel image task as soon as the cell goes offscreen (optional):

- (void)collectionView:(UICollectionView *)collectionView didEndDisplayingCell:(UICollectionViewCell *)cell forItemAtIndexPath:(NSIndexPath *)indexPath {
    DFImageView *imageView = (id)[cell viewWithTag:15];
    [imageView prepareForReuse];
}

Preheating Images

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

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

Requesting Image for PHAsset

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

Progressive Image Decoding

// Enable progressive image decoding
[DFImageManagerConfiguration setAllowsProgressiveImage:YES];

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

DFImageTask *task = .../ Create image task
task.progressiveImageHandler = ^(UIImage *__nonnull image){
    imageView.image = image;
};
[task 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

DFImageManagerConfiguration *configuration = [[DFImageManagerConfiguration alloc] initWithFetcher:fetcher];
configuration.decoder = decoder;
configuration.processor = processor;
configuration.cache = cache;

[DFImageManager setSharedManager:[[DFImageManager alloc] initWithConfiguration:configuration]];

Composing Image Managers

The DFCompositeImageManager allows clients to construct a tree of responsibility from multiple image managers, 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. For more info see Composing Image Managers.

id<DFImageManaging> manager = <#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];

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

To install DFImageManager add a dependency in your Podfile:

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

By default it will install these subspecs (if they are available for your platform):

• DFImageManager/Core - DFImageManager core classes
• DFImageManager/UI - UI components
• DFImageManager/PhotosKit - Photos Framework 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 subspecs include them in your Podfile:

# Podfile
pod 'DFImageManager'
pod 'DFImageManager/AFNetworking'
pod 'DFImageManager/GIF'
pod 'DFImageManager/WebP'

Requirements

• iOS 7.0+ / watchOS 2
• Xcode 6.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 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.