carlos7646 / dfimagemanager

Modern iOS framework for fetching images from various sources. Delivers consistency, extensibility, and performance.

DFImageManager

Modern iOS framework for fetching, caching, processing, and preheating images from various sources. It uses latest advancements in iOS SDK and doesn't reinvent existing technologies. It provides a powerful API that will extend the capabilities of your app.

Supported resources

• NSURL with http, https, ftp, file, and data schemes
• PHAsset and NSURL with com.github.kean.photos-kit scheme
• DFALAsset, ALAsset and NSURL with assets-library scheme

Features

• Zero config, yet immense customization and extensibility.
• Uses latest advancements in Foundation URL Loading System including NSURLSession that supports SPDY protocol.
• Extreme performance even on outdated devices. Asynchronous and thread safe.
• 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. Read more
• Separate memory cache for decompressed and processed images. Fine grained control over memory cache.
• Centralized image decompression, resizing and processing. Resizing provides a lack of misaligned images and lower memory footprint. Fully customizable.
• Automatic preheating of images that are close to the viewport.
• Groups similar requests and never executes them twice. This is true for both fetching and processing. Intelligent control over which requests are considered equivalent (both in terms of fetching and processing).
• High quality code base. Follows best design principles and patterns, including dependency injection used throughout.
• Unit tests help to maintain the project and ensure its future growth.

Getting Started

• Download the latest release or development version
• Take a look at the comprehensive demo projects
• Check out the complete documentation
• Experiment with the APIs in a Swift playground available in the project
• View growing project Wiki
• Install using CocoaPods, import <DFImageManager/DFImageManagerKit.h> and enjoy!

Requirements

iOS 7.0+

Usage

Zero config image fetching

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

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

Add options

DFImageRequestOptions *options = [DFImageRequestOptions new];
options.allowsClipping = YES;
options.progressHandler = ^(double progress){
  // Observe progress
};

NSURL *imageURL = [NSURL URLWithString:@"http://..."];
[[DFImageManager sharedManager] requestImageForResource:imageURL targetSize:CGSizeMake(100.f, 100.f) contentMode:DFImageContentModeAspectFill options:options completion:^(UIImage *image, NSDictionary *info) {
  // Image is resized and clipped to fill 100x100px square
}];

Options can be specialized and packed into DFImageRequest

Use DFURLImageRequestOptions (DFImageRequestOptions subclass) to set request cache policy. Create instance of DFImageRequest to pack all request parameters.

DFURLImageRequestOptions *options = [DFURLImageRequestOptions new];
options.allowsClipping = YES;
options.cachePolicy = NSURLRequestReturnCacheDataDontLoad;
options.progressHandler = ^(double progress){
  // Observe progress
};
    
// Use universal image request container
DFImageRequest *request = [[DFImageRequest alloc] initWithResource:[NSURL URLWithString:@"http://..."] targetSize:CGSizeMake(100.f, 100.f) contentMode:DFImageContentModeAspectFill options:options];
    
[[DFImageManager sharedManager] requestImageForRequest:request completion:^(UIImage *image, NSDictionary *info) {
  // Image is resized and clipped to 100x100 px square
}];

Create composite requests from array of DFImageRequest objects

DFImageRequest *previewRequest = [[DFImageRequest alloc] initWithResource:[NSURL URLWithString:@"http://preview"]];
DFImageRequest *fullsizeImageRequest = [[DFImageRequest alloc] initWithResource:[NSURL URLWithString:@"http://fullsize_image"]];

NSArray *requests = @[ previewRequest, fullsizeImageRequest ];
[DFCompositeImageFetchOperation requestImageForRequests:requests handler:^(UIImage *image, NSDictionary *info, DFImageRequest *request) {
  // Handler does just what you would expect
  // For more info see DFCompositeImageFetchOperation docs
}];

There are many smart ways how composite requests can be used.

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 = ...;
// All options are enabled be default
imageView.managesRequestPriorities = YES;
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:@[ ... ]];

Use the same DFImageManaging APIs for PHAsset, ALAsset and other classes

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

// You can use easily serializable asset NSURL for fetching too
NSURL *assetURL = [NSURL df_assetURLWithAsset:asset];
    
// There are Photos Kit-specific options as well
DFPhotosKitImageRequestOptions *options = [DFPhotosKitImageRequestOptions new];
options.version = PHImageRequestOptionsVersionUnadjusted;
options.deliveryMode = PHImageRequestOptionsDeliveryModeHighQualityFormat;

// Use full power of polymorphism
DFImageRequest *request = [[DFImageRequest alloc] initWithResource:assetURL targetSize:DFImageMaximumSize contentMode:DFImageContentModeAspectFill options:options];

Leverage power of composite managers

The sharedManager provided by DFImageManager is an instance of DFCompositeImageManager class that implements DFImageManaging protocol. It dynamically dispatches image requests between multiple image managers that construct a chain of responsibility. What it means is that sharedManager doesn't only support URL image fetching, it also supports assets (PHAsset, ALAsset and their URLs) and it can be easily extended to support your custom classes. For more info see Using DFCompositeImageManager.

// 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] ];
DFCompositeImageManager *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 jam-packed with other features. There are much more options for customization and room for extension. For more info check out the complete documentation and project Wiki

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.

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

If you want to use the latest DFImageManager features before the new version is released, you can specify the :head flag in you podfile.

platform :ios, '7.0'
pod 'DFImageManager', :head

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, submit a pull request.

DFImageManager is constantly improving. Help to make it better!

Contacts

Alexander Grebenyuk (@a_grebenyuk)

License

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